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Preface 


This programming guide describes the Micro VMS workstation graphics software. 

It contains general information about basic Micro VMS graphics concepts, a tutorial 
for learning to program with Micro VMS graphics, and complete descriptions and 
reference information about the system routines for all callable functions. 


Intended Audience 

This guide is intended for general users and programmers who want to learn the 
concepts and use appropriate routines in graphics application programs. 


Structure of This Document 

This guide is divided into four major sections, MicroVMS Workstation Graphics 
Concepts, How to Program with MicroVMS Workstation Graphics, UIS Routine 
Descriptions, and UIS Device Coordinate (UISDC) Routines. These sections are 
briefly described in the following paragraphs. 

Part I — MicroVMS Workstation Graphics Concepts 

This section contains five chapters which provide a general overview of the basic 
concepts of MicroVMS workstation graphics. 

• Chapter 1 — System Description 

This chapter briefly describes the hardware, software, and options that are parts 
of the MicroVMS workstation system. 

• Chapter 2 — Display Management Concepts 

This chapter discusses the concepts of world coordinates, device coordinates, 
virtual displays, windows, viewports, window and viewport scaling, and 
distortion of graphic objects. 

• Chapter 3 — Graphic Objects and Attributes 

This chapter describes and shows the relationship between graphics routines, 
attribute blocks, text attributes, graphics attributes, and segments. 
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• Chapter 4 — Color Concepts 

This chapter discusses the various color and intensity environments supported by 
the VAXstation color systems. 

• Chapter 5 — Input Devices 

This chapter shows how the workstation input devices relate to the workstation 
graphics system. 

Part II — How to Program with MicroVMS Workstation Graphics 

This section contains step-by-step tutorial information about writing application 
programs using MicroVMS graphics. Practical programming examples are provided 
throughout this section. It is divided according to routine functions into the following 
chapters: 

• Chapter 6 — Programming Considerations 

This chapter describes the programming interface and topics relating to program 
execution. * 

• Chapter 7 — Creating Basic Graphic Objects 

This chapter describes the underlying structures and shows how to create graphic 
objects. 

• Chapter 8 — Display Windows and Viewports 

This chapter shows how to create and manipulate display windows and display 
viewports. 

• Chapter 9 — General Attributes 

This chapter describes writing modeS;, display background and foreground, and 
the writing index. 

• Chapter 10 — Text Attributes 

This chapter describes how attributes may be used to enhance and modify text. 

• Chapter 11 — Graphics Attributes 

This chapter describes how attributes may be used to enhance and modify the 
appearance of graphic objects. 

• Chapter 12 — Inquiry Routines 

This chapter discusses how information can be returned to the application 
program. 

• Chapter 13 — Display Lists and Segmentation 

This chapter describes how to create and manipulate display lists and segments. 
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• Chapter 14 — Geometric and Attribute Transformations 

This chapter describes the various ways graphic objects and components of 
graphic objects can be manipulated with the respect to the coordinate space. 

• Chapter 15 — Metafiles and Private Data 

This chapter discusses how to extract the contents of a display list and store the 
data in a buffer or external file. There is additional information about how to 
associate private data with a graphics display. 

• Chapter 16 — Programming in Color 

The chapter describes how to create and display graphic objects in color. 

• Chapter 17 — Asynchronous System Trap Routines 

This chapter discusses how to make use of program-related events to increase 
the interactive nature of your applications. 

Part III — UlS Routine Descriptions 

This section contains reference material about the device-independent Micro VMS 
workstation graphics routines. 

• Chapter 18 — UIS Routines Descriptions 

• UIS Routine Descriptions 

Part IV — UIS Device Coordinate (UlSDC) Routines 

This section contains reference material about device-dependent Micro VMS 
workstation graphics routines. 

• Chapter 19 — UIS Device Coordinate Graphics Routines 

• UISDC Routines 

Appendix A — Summary of UIS Calling Sequences 

Appendix B — Summary of UISDC Calling Sequences 

Appendix C — UIS Fonts 

Appendix D — UIS Fill Patterns 

Appendix E — Error Messages 

Appendix F — Obsolete Routines 

Glossary 

NOTE: For documentation on VMS data types, see Appendix A of the MicroVMS 
Workstation Version 3.0 Release Notes. 
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How To Use This Guide 

This guide is designed so that it can be used in two different ways: 

• It can be used as a learning tool by general users and programmers new to 
graphics software and Micro VMS workstation graphics. 

• It can be used as a reference tool by programmers already familiar with graphics 
software in general and/or Micro VMS workstation graphics. 

Inexperienced User 

If you are unfamiliar with the Micro VMS workstation graphics system, you should 
begin by reading Part I of this guide. It gives you an overview of the graphics 
concepts discussed in subsequent sections of the book. 

The programming tutorial in Part II provides a step-by-step approach for learning 
how to write applications that take advantage of the graphics capabilities of the 
MicroVMS workstation. 

Part III provides you with reference information about all of the UIS routines used in 
MicroVMS workstation graphics. It is easier to use after you have read Part II of this 
guide. 

Part IV contains appendices that provide reference material about UISDC graphics 
routines and error messages. 

Experienced User 

Once you have become familiar with MicroVMS workstation graphics, you will 
seldom need to refer to Part I of this guide, except when reviewing basic concepts. 

Refer to Part II for examples and suggestions on the proper use of MicroVMS 
workstation graphics routines. 

Part III is an alphabetically arranged reference section that you can use to get detailed 
descriptions of MicroVMS workstation graphics routines. Before using this section, 
you should already be familiar with Parts I and II of this guide. 

Part IV contains appendices that provide reference material about UISDC graphics 
routines and error messages. 
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Associated Documents 

The following Micro VMS manuals are related to this guide: 

• MicroVMS Workstation User's Guide 

• MicroVMS Workstation Video Device Driver Manual 

• MicroVMS Workstation Guide to Printing Graphics 

• MicroVMS User’s Manual 

• MicroVMS User's Primer 

• MicroVMS Programmer's Manual 

• MicroVMS FORTRAN Programmer's Primer 

• MicroVMS Programming Pocket Reference 

• Installing or Upgrading MicroVMS From Diskettes 

• Installing or Upgrading MicroVMS From a Tape Cartridge 


Conventions Used in This Document 

This manual uses the following conventions: 


Convention 


|CTRL/x| 


$ SHOW TIME 
05-JUN-1986 11:55:22 

$ TYPE MYFILE.DAT 


file-spec,... 


Meaning 

A symbol with a one- to six-character abbreviation 
indicates that you press a key on the terminal, for example, 

[Ht]. 

The phrase CTRL/x indicates that you must press the key 
labeled CTRL while you simultaneously press another key, 
for example, CTRL/C, CTRL/Y, CTRL/O. 

Command examples show all output lines or prompting 
characters that the system prints or displays in black 
letters. All user-entered commands are shown in red 
letters. 

Vertical series of periods, or ellipsis, mean either that not 
all the data that the system would display in response to 
the particular command is shown or that not all the data a 
user would enter is shown. 

Horizontal ellipsis indicates that additional parameters, 
values, or information can be entered. 
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Convention 

Meaning 

[logical-name] 

Square brackets indicate that the enclosed item is optional. 
(Square brackets are not, however, optional in the syntax 
of a directory name in a file specification or in the syntax 
of a substring specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer to double 
quotation marks ("). The term apostrophe (') is used to 
refer to a single quotation mark. 





New and Changed Features 


The following sections describes changes to the programming interface since UIS 
Version 2.0. 


New UIS Routines 

The following UIS routines were added. 


Function Routine 

AST-enabling UIS$SET_ADDOPT_AST 

UIS$SET_EXPAND_ICON_AST 

UIS$SET_TB_AST 

UIS$SET_SHRINK_TO_ICON_AST 

Color UIS$CREATE_COLOR_MAP 

UIS$CREATE_COLOR_MAP_SEG 

UIS$DELETE_COLOR_MAP 

UIS$DELETE_COLOR_MAP_SEG 

UIS$GET_COLORS 

UIS$GET_HW_COLOR_INFO 

UIS$GET_INTENSITIES 

UIS$GET_VCM_ID 

UIS$HLS_TO_RGB 

UIS$HSV_TO_RGB 

UIS$RESTORE_CMS_COLORS 

UIS$RGB_TO_HLS 

UIS$RGB_TO_HSV 

UIS$SET_JNTENSITIES 
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Function Routine 

Display list UIS$COPY_OBJECT 

UIS$DELETE_OBJECT 

U1S$DELETE-PRIVATE 

UIS$EXECUTE 

UIS$EXECUTE -DISPLAY 

UIS$EXTRACT_HEADER 

UIS$EXTRAGT-OBJECT 

UISSEXTRACT-PRIVATE 

UIS$EXTRACT-REGION 

UISSEXTRACT-TRAILER 

UIS$FIND-PRIMITIVE 

UIS$FIND-SEGMENT 

UIS$GET-CURRENT-OBJECT 

UIS$GET-NEXT-OBJECT 

UIS$GET-OBJECT_ATTRIBUTES 

UIS$GET-PARENT-SEGMENT 

UIS$GET-PREVIOUS-OBJECT 

UIS$GET-ROOT-SEGMENT 

UIS$INSERT-OBJECT 

UISSPRIVATE 

UISSSET-INSERTION-POSITION 

UIS$TRANSFORM-OBJECT 

Graphics UIS$LINE 

UISSLINE-ARRAY 

Keyboard and pointer UIS$CREATE—TB 

UIS$DELETE-TB 
UIS$DISABLE-TB 
UIS$ENABLE-TB 
UIS$GET-TB-INFO 
UIS$GET-TB_POSITION 
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Function Routine 

^ UIS$GET_CHAR_ROTATION 

UIS$GET_CHAR_SIZE 
UIS$GET_CHAR_SLANT 
UIS$GET_FONT_ATTRIBUTES 
UIS$GET_TEXT_FORMATTING 
UIS$GET_TEXT_MARGINS 
UIS$GET_TEXT_PATH 
UIS$GET_TEXT_SLOPE 
UIS$SET_CHAR_ROTATION 
UIS$SET_CHAR_SIZE 
UIS$SET_CHAR_SLANT 
UIS$SET_TEXT_FORMATTING 
UIS$SET_TEXT_MARGINS 
UIS$SET_TEXT_PATH 
UIS$SET_TEXT_SLOPE 

Windowing UIS$EXPAND_ICON 

UIS$GET_VIEWPORT_ICON 

UIS$GET_WINDOW_SIZE 

UIS$SHRINK_TO_ICON 


New UlSDC Routines 

The following UlSDC routines are new for Version 3.0. 

• UlSDC$ALLOCATE_DOP 

• UlSDC$EXECUTE_DOP_ASYNCH 

• UlSDC$EXECUTE_DOP_SYNCH 

• U1SDC$GET_CHAR_SIZE 

• U1SDC$GET_TEXT_MARG1NS 

• U1SDC$LINE 

• U1SDC$LINE-ARRAY 

• UlSDC$LOAD_BlTMAP 

• UlSDC$QUEUE_DOP 

• U1SDC$SET_CHAR_S1ZE 

• U1SDC$SET_TEXT_MARG1NS 
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New Chapters 

Three new chapters describing color concepts and color programming considerations 
have been added since Version 2.0. 

• Color Concepts 

• Geometric and Attribute Transformations 

• Programming in Color 

New UlS Writing Modes 

Five new writing modes have been added since Version 2.0. 

• UIS$C_MODE_BIC 

• UIS$C_MODE_BICN 

• UIS$C_MODE_BIS 

• UIS$C_MODE_BISN 

• UIS$C_MODE_COPYN 

New Technical Character Set Fonts 

Twelve new technical character set fonts have been added since Version 2.0. 

New Text Attributes 

The following new text attributes have been added to the programming interface. 

• Character rotation 

• Character scaling 

• Character slant 

• Text formatting 

• Text margins 

• Text path 

• Text slope 
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Changes to Existing UlS Routines 

UIS$BEGIN_SEGMENT 

UIS$BEGIN—SEGMENT now returns segment identifier that can be referenced by 
other display list routines. For example, this allows traversing segments and segment 
paths. 

UIS$MEASURE_TEXT and UIS$TEXT 

You can now use control lists with UIS$TEXT and UIS$MEASURE_TEXT. 

UIS$DISABLE_DISPLAY_LIST and UIS$ENABLE_DiSPLAY_LIST 

Additional arguments have been included that control display screen and display list 
updates. 

UIS$SET_POINTER_PATTERN and UISDC$SET_POINTER_PATTERN 

If you are using a color system, you can now specify a pointer pattern outline. 

Display Lists and Segmentation 

The chapter on display lists and segmentation has been expanded with more 
examples. 


UlS Metafiles 

You can create and store metafiles of generically encoded instructions as files and 
reexecute the file. 


Shrinking Viewports and Expanding Icons 

Applications can now shrink display viewports and expand icons. 
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Obsolete Version 2.0 UlS Routines 

The following routines are obsolete. 

• UIS$GET_LEFT_MARGIN 

• UIS$SET_LEFT_MARGIN 

• UISDC$GET_LEFT_MARGIN 

• UISDC$SET_LEFT_MARGIN 



PART I MicroVMS Workstation 
Graphics Concepts 




Chapter 1 
System Description 


1.1 Overview 

This chapter introduces the Micro VMS workstation graphics system. It is divided 
into two parts: 

• A summary of typical workstation hardware 

• A description of the graphics software 


1.2 VAXstation Hardware 

The Micro VMS workstation can be used as a standalone system. It has all the 
components necessary to run programs and perform tasks without being connected 
to a host computer. It can also be connected to a host computer and used as a part 
of a network in a larger system. 

The Micro VMS workstation typically consists of a configuration of the following 
hardware: 

• Processor 

• Display monitor 

• Keyboard 

• Three-button mouse or a tablet 

• Communications board 

• Printer 

An illustration of the typical Micro VMS workstation hardware is provided in 
Figure 1-1. 
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System Description 


Figure 1-1 Typical Micro VMS Workstation Hardware 



1.2.1 Processor 

The processor is the heart of the Micro VMS workstation system. The processor 
contains the disk drives, all of the memory, any options, and communications 
hardware for the system. Usually, it houses both fixed and flexible disk drives. The 
amount of memory it has can vary, depending upon the options installed. 


1.2.2 Monitor 

The monitor displays text and graphics information. It is a high-resolution bitmap 
device that can be used to display black-and-white, grey scale, or color graphics. 
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1.2.3 Keyboard 

The keyboard used with the workstation is the DIGITAL LK201, a standard low- 
profile style keyboard. This keyboard consists of: 

• A top row of function keys which are user-definable 

• A numeric keypad which is also user definable 

• A special keypad which has arrow keys and function keys 

• A standard alphanumeric keypad 

Some of the top row of function keys are control keys that enable the user to: 

• Hold the screen 

• Display the operator window 

• Switch the windowing system 

• Change the active window 

In this row, there are also keys that call functions such as cancel, exit, help, and 
provide aid in editing. 

The function keys and numeric keypad keys can be defined by an application 
program to perform functions suited to a particular application. The arrow keys can 
be used to move the keyboard cursor within applications. The alphanumeric keypad 
is similar in function to a typewriter keyboard. 

1.2.4 Mouse 

The three-button mouse is a medium-resolution, relative pointing device. It is the 
primary means for a user to point to an object on the screen. When the mouse is 
rolled on a flat surface, the pointer on the screen moves in a similar fashion. The 
buttons are used to make selections. 

1.2.5 Tablet 

The tablet is a high-resolution, absolute positioning device. It consists of a flat tablet, 
a puck with buttons, and a pen with buttons. When the puck or pen are moved 
on the tablet, the pointer on the display screen moves in an identical fashion. The 
buttons are used for selection. 
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1.2.6 Communications Board 

The communications board allows the system to be connected with and communicate 
with other computers. 

1.2.7 Printer 

The Micro VMS workstation can have a printer connected to the processor's console 
port or can access printers located at remote location through the network. You can 
print any rectangular portion of display screen. 


1.3 Software 

The Micro VMS workstation graphics software is a versatile graphics and windowing 
interface. It is designed to be used on any of the Micro VAX family of workstation 
products (such as VAXstations). This graphics interface allows the user to write 
application programs in VAX MACRO, VAX BLISS, and many other high-level 
languages. Application programs written to take advantage of this software will be 
able to create and manipulate windows, display multiple styles of text and sizes, 
receive input, and draw graphic objects in the created windows. 

1.3.1 Graphics Routine Types 

The Micro VMS workstation graphics software is composed of callable routines that 
can be accessed from a high-level programming language. An application program 
can perform graphics and windowing functions by making calls to the appropriate 
routines. This software contains routines for creating display windows, drawing lines 
and text, and building graphic objects. 

Routines fall into the following general categories: 

• AST-enabling routines 

• Attribute routines 

• Color routines 

• Display list routines 

• Graphics and text routines 

• Inquiry routines 

• Keyboard routines 

• Pointer routines 

• Sound routines 
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• Windowing routines 

• Device coordinate routines 

1.3.2 Human Interface 

The Micro VMS workstation provides an interface between the graphics software and 
the user. This interface is called the human interface because it acts to aid the human 
operator to use the workstation. 

One of the things that this interface does is make it easy for the user to create new 
terminal windows on the screen. The MicroVMS workstation provides the operator 
with the capability of having the equivalent of many terminals at his or her disposal. 
A user can easily create emulated DIGITAL VT220 or Tektronix TEK4014 terminals 
by merely selecting a menu item which creates a window on the screen. 

The operator can also control the placement of windows on the screen. Windows can 
be moved anywhere on the screen (or even partially off of it). They can be hidden 
from view, pushed behind other windows, popped in front of other windows, and so 
on. The following list shows some of the operations that are possible. 

• Create a new VT220 or TEK4014 terminal window 

• Move a window to a different part of the screen 

• Push a window behind other windows 

• Pop a window in front of other windows 

• Shrink a viewport to a icon 

• Change the size of a window 

• Delete a window 

• Switch the keyboard from one window to another 

• Suspend all screen activity (hold screen) 

• Print any portion (or all) of a window or the screen 

• Set workstation attributes 

• Get online help 
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1.3.2.1 Terminal Emulation 

You can create emulated terminals on the Micro VMS workstation. The programming 
interface and the capabilities of emulated terminals are the same as the programming 
interface and capabilities of the corresponding real terminal. The appearance of an 
emulated terminal on the Micro VMS workstation screen is similar to that of the 
corresponding real terminal. (It will not be completely identical due to hardware 
differences.) 

An advantage of having several terminal windows is that a job can be started on one 
terminal, and while it's left running, another terminal can be created and another job 
started. The user can create as many terminals as desired and switch back and forth 
between them at will. 

VT220/TEK4014 

The VAXstation can emulate the DIGITAL VT220 or Tektronix TEK4014 terminal. 
There can be any number of VT220 or TEK4014 windows on the screen 
simultaneously. However, only one window may use the keyboard at any one 
time. The keyboard is assigned to a window by the operator. 

VT220 ANSI and DIGITAL private escape sequences, and TEK4014 escape sequences, 
are interpreted and translated into the appropriate graphics routines. 

Programs written using the VAX/VMS operating system will operate in a VTIOO or 
VT220 workstation window without modification. 

1.3.2.2 Communication Tools 

Users can communicate with the software interface through either the mouse, tablet, 
or keyboard. 

Mouse and Tablet 

The mouse and tablet control a cursor called a pointer on the screen. When the 
mouse or tablet is manipulated by the user, the pointer moves on the screen. The 
pointer is used by an operator to point to things on the screen, such as an item in 
a menu. The buttons associated with mouse and tablet are used to make selections. 
The pointer, in combination with buttons on the mouse, can perform several tasks: 

• Point to objects on the screen 

• Select objects on the screen 

• Move objects around on the screen 

• Push and pop windows on th'e screen 
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• Call menus to the screen 

• Switch the keyboard between emulated terminals or windows 

• Perform application designated functions 

Keyboard 

You can use the keyboard to perform the following functions: 

• Respond to system prompts 

• Provide control keys, such as [hold screen | and I cycle | 

• Provide special keys, such as I help] 

• Enter data and information into a screen window 

• Move a cursor in a window on the screen 

• Perform application specific functions 

1.3.3 Windowing Feature 

The graphics software allows a large number of windows to be created and 
maintained at the same time. Graphics routines are provided to handle the creation, 
deletion, and manipulation of overlapping windows. Windows can be popped to 
the front of the screen, pushed to the background, moved around the screen to a 
new position, and completely deleted from the screen. The amount and size of 
information that appears in a window can also be controlled. 

1.3.4 Graphics Capabilities 

Routines are provided to create new displays and draw graphics within the created 
displays. A display list, which is an encoded description of the routines used to 
create the contents of a display, is kept in memory. The display list enables a 
program to easily pan and zoom portions of a display without having to redraw the 
entire display. Scaling of the display is done automatically by the graphics software. 
A display, or a portion of a display, can be mapped into one or more windows on 
the screen. 





Chapter 2 

Display Management Concepts 


2.1 Overview 

This chapter discusses the basic concepts involved in creating a graphic object and 
displaying it on the workstation screen. Some of the topics covered in this chapter 
are as follows: 

• Virtual displays 

• Display windows 

• Display viewports 

• World and device coordinates 

• Display window and viewport scaling 

2.1.1 Summary 

The Micro VMS workstation graphics software enables application programs to build 
graphic objects and display them on the workstation screen. 

An application program that takes full advantage of the capabilities of the Micro VMS 
workstation graphics can do the following things: 

• Create a virtual display. 

• Draw graphics and text into the virtual display. 

• Open windows into the virtual display for viewing on an output device. 

• Map the windows into display viewports on the workstation screen. 

• Manipulate the windows and viewports to display as much or as little of the 
virtual display as desired. 

• Pan, zoom in and out, resize, and duplicate the display windows. 

• Manipulate display lists. 
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To do these things, an application program must first create a virtual display in which 
to build the object. A virtual display can be thought of as a conceptual display 
space that has no actual physical size or shape. This conceptual display space, 
called the world coordinate system, is defined by the application program in terms of 
world coordinates. World coordinates are arbitrary units of measure selected by the 
application program that specify locations (or points) in the world coordinate system 
using values that are convenient to the application. 

World coordinates are automatically translated to normalized coordinates (by the 
graphics software) before being mapped to an output device. Normalized coordinates 
convert user world coordinates into a single device-independent coordinate system 
so that the user does not have to deal with several coordinate systems. Normalized 
coordinates are automatically mapped to the device-dependent coordinates of the 
physical output device. 

A graphic object constructed in a virtual display is not available for display on 
an output device until a display window and display viewport are created by the 
application program. 

A display window defines what portion of the graphic object in a virtual display is to 
be viewed. By creating the display window, the program is making the information 
in the virtual display potentially visible to the user. The information in the display 
window is not actually visible to a user until the display window is mapped to a 
display viewport. 

A display viewport is the physical region on a display device that is created by the 
Micro VMS workstation software and controlled by the user. The display viewport 
is the physical representation of the display window that is mapped to it. It enables 
a user to view the graphic object that is inside the display window. Figure 2-1 
illustrates the relationship between the virtual display, display window, and display 
viewport. 

Physical device coordinates are used in mapping a display window to a display 
viewport. Physical device coordinates are the physical points on the display screen 
that are used to locate the graphic object. The process of mapping a graphic object 
from the world coordinates of the display window to the device coordinates of the 
display viewport is called a viewing transformation. Viewing transformations are 
handled automatically by the graphics software. 

The world coordinates of the display window can be manipulated in relation to 
the world coordinates of the virtual display to achieve the effects of panning and 
zooming the graphic object in the display viewport. 
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Figure 2-1 Virtual Display, Display Window, and Display Viewport 



2.2 Coordinate Systems 

The Micro VMS workstation graphics environment can be thought of as a two 
dimensional plane. Because of this, the Cartesian coordinate system applies in 
describing points within this environment. Cartesian coordinates take the form 
of x,y, where x is the horizonal axis and y is the vertical axis. A point on this plane is 
specified by a coordinate pair. The area of this plane that is specified by coordinate 
pairs is called the coordinate space. 

The Micro VMS workstation graphics software makes use of four Cartesian coordinate 
systems: world, normalized, absolute, and viewport-relative device coordinates. 

2.2.1 Device-Independent Coordinate Systems 

Device-independent coordinate systems mediate between the requirements of the 
application program and the graphics subsystem versus those of the output device. 




2-4 Display Management Concepts 


2.2.1.1 World Coordinates 

An application program uses world coordinates to describe a virtual display and to 
build a graphic object within it. Initially, the application program creates a virtual 
display and specifies a convenient world coordinate system to use when referring to 
the virtual display. Next, the program specifies the size and location of objects to be 
created within the virtual display, using the same coordinates. 

World coordinates are device-independent Cartesian coordinates that are specified 
by the application program. They provide a means of locating the points in a virtual 
display. The range of world coordinate values is specified when the virtual display 
is created. In this way, the virtual display can be created to any proportions that 
are selected by the application program. World coordinate values are given as 
floating-point numbers. 

The world coordinate system can represent any unit of measure. World coordinates 
enable application programs to use convenient increments of measurement when 
constructing a graphic object. If the program is accessing information from a data 
base, it could specify world coordinates that are meaningful for the data used. For 
instance, if an application is drawing a chart showing the sales of a company's 
product during a holiday season, it could use convenient measurements representing 
units sold in thousands versus the time in weeks. Or, if the application program is 
drawing a graphic object, it could use measurements that make sense for the object. 
For example, a virtual display containing a map of the United States might logically 
have world coordinates representing measurements in miles or kilometers. A floor 
plan of a house might likely use world coordinates representing feet and inches, or 
meters and centimeters. 

Figure 2-2 shows a world coordinate system that describes a virtual display in which 
an object has been constructed. 
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Figure 2-2 World Coordinate System and Virtual Display 



2.2.1.2 Normalized Coordinates 

Normalized coordinates are device-independent coordinates that are defined by the 
graphics software. They are used to describe the virtual display in physical terms 
that any output device can use. An output device cannot use the arbitrary world 
coordinates that an application program uses to describe a virtual display. Instead, 
each kind of output device has its own device-specific coordinates that it uses to 
locate and build the graphic object. Normalized coordinates can be thought of as a 
way for the graphics software to normalize these different coordinate systems so that 
a graphic object can be mapped from a virtual display to any output device. 
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Normalized coordinates are not directly used or manipulated by application 
programs. They are used internally by the graphics software. The mapping of 
normalized coordinates into device-specific display coordinates is handled entirely by 
the software. 

Normalized coordinates provide a means of delaying the actual mapping of an 
application program's world coordinates to device-specific coordinates until the 
actual output device is established. 

2.2.2 Device-Dependent Coordinate Systems 

Output devices use device-dependent coordinate systems to map graphic objects on 
the display screen or to print objects on a printer. Device-dependent coordinates are 
physical device coordinates that denote some physical unit of measure such as pixels, 
centimeters, or inches. Such physical device coordinates reflect device-dependent 
mapping and drawing characteristics of the output device. 

2.2.2.1 Absolute Device Coordinates 

Absolute device coordinates are physical device-dependent Cartesian coordinates 
that specify positions on the Micro VMS workstation display screen. The position 
is specified in centimeters relative to the lower-left comer of the display screen. 
Typically, viewport placement, pointer position, and tablet placement use absolute 
coordinates. Figure 2-3 illustrates viewport placement on the VAXstation screen 
relative to the lower-left corner of the screen. 
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Figure 2-3 Absolute Device Coordinates 



Display Screen ZK 5429-86 

2.2.2.2 Viewport-Relative Device Coordinates 

Many Micro VMS workstation graphics software routines utilize a special type of 
physical device coordinates called viewport relative device coordinates. Viewport 
relative device coordinates are physical device coordinates that specify positions 
within a display viewport. The position specified is relative to the lower-left corner 
of the viewport. Viewport-relative device coordinates are always positive. 

Viewport-relative device coordinates are specified in units of pixels. A pixel is the 
smallest displayable unit on a display screen. The Micro VMS workstation graphics 
software takes care of all mapping of display windows to the display screen. 
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Viewport-relative device coordinates are used in mapping graphic objects from a 
display window to a display viewport on a physical display device. 

In order to display a graphic object in a display viewport on a display device, the 
world coordinates of the object must be transformed to the viewport-relative device 
coordinates of the display device. 

Figure 2-4 shows an object in a display window being mapped to a display viewport 
on a physical display device. In this illustration, the world coordinates of the display 
window undergo a viewing transformation to the physical device coordinates of the 
display device. 

Figure 2-4 Mapping a Display Window to a Display Viewport 
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2.3 Virtual Displays 

A virtual display is a conceptual display space created by an application program. It 
is used by an application program as the place where graphic objects are constructed. 
All text and graphics output of the application program are written to a virtual 
display. 
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A virtual display has no physical size (dimensions of length and width). Therefore, 
objects constructed in a virtual display also have no actual physical dimensions. You 
cannot measure a virtual display or the graphic objects within it. 

Instead, a virtual display and the objects within it have relative sizes and proportions. 
The comparison of the relative proportions of the vertical and horizontal components 
of an object in a virtual display is called the aspect ratio of the object. The aspect 
ratio is used in referring to an object's relative size in a virtual display. 

To create a virtual display, an application program specifies a coordinate range in 
the world coordinate system. The coordinate range establishes the relative size, or 
aspect ratio, of the virtual display. Objects constructed in the virtual display are also 
specified in terms of world coordinates and also have an aspect ratio. The aspect 
ratio will later affect how the virtual display and the objects it contains map to the 
display window. 

Refer back to Figure 2-2 which shows a graphic object drawn in a virtual display. 
Both the virtual display and the graphics object are specified in terms of world 
coordinates. 


2.4 Display Windows 

A display window is used to display all or a part of the contents of a virtual display. 
Display windows are created by an application program. A display window is used 
by the application program to control how much of a virtual display is potentially 
available for the user to view. A display window can be the size of an entire virtual 
display or just a small portion of it. There can be one or several display windows 
active at one time in a virtual display. 

The relative proportions and location of a display window are specified by an 
application program in terms of world coordinates. Therefore, the amount of the 
virtual display that is encompassed by a display window is relative to the world 
coordinates of the virtual display. By specifying the proportions and location of the 
display window, an application program determines what portion of the graphic 
object within a virtual display is viewable. 

The world coordinate boundaries of a display window define what is called a clipping 
rectangle. Any graphic object that lies within the clipping rectangle is potentially 
visible in the display viewport. Objects that fall outside of the clipping rectangle are 
not viewable and are clipped from the window as illustrated in Figure 2-5. 
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Figure 2-5 Display Window in a Virtual Display 



2.5 Display Viewports 

A display viewport is the area of the physical display screen to which a display 
window is mapped. The display viewport is the user's means of viewing the contents 
of a display window. A display viewport is always associated with a display window 
and is the mechanism by which the display window is displayed on the screen. 

They can vary in size and shape, and can be located anywhere on the physical 
display screen. There can be as many viewports as desired on the screen at a time. 

If viewports overlap each other, they will occlude in the areas that overlap. The 
last viewport created will be on top and visible. However, the operator can modify 
which viewport is on top at any one time. 

The display window is mapped and scaled to the display viewport automatically 
by the graphics software. Normally, the display window is mapped to the display 
viewport on a one-to-one basis. That is, the boundaries of the display viewport 
always implicitly default to the same size and shape as that of the display window. 
However, it is possible for the application program to explicitly specify that the 
display window be of a size or shape that is different than that of the display 
viewport; or, that the display viewport be of a size or shape that is different from 
that of the display window. The effects that are achieved when the display window 
and display viewport are of a different size or shape are discussed in the following 
sections of this chapter. 
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Refer to Figure 2-6 for an illustration of the relationship between the virtual display, 
the display window and the display viewport. This illustration shows how a graphics 
object in a virtual display is clipped to the display window, scaled and mapped into 
a display viewport, and displayed on a physical display device such as a terminal 
screen. 

Figure 2-6 Displaying a Graphic Object 
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2.6 Display Window and Viewport Scaling 

Graphic objects on the display screen can be magnified or reduced in size by 
manipulating the relative sizes of the display window and the display viewport. 

The following list describes the various effects that can be achieved and the method 
used to accomplish each effect. 

Magnifying 

To magnify the graphic object, use one of these two methods: 

• Decrease the size of the display window without altering the viewport size. 

• Increase the size of the display viewport without altering the window size. 
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Reducing 

To reduce the graphic object, use one of these two methods: 

• Increase the size of the display window without altering the viewport size. 

• Decrease the size of the display viewport without altering the window size. 

Panning 

To pan the graphic object, use this method: 

• Move the display window within the virtual display without altering the display 
viewport. 

Changing View Size 

You can change the area of the virtual display that is being viewed, without 
performing scaling, in the following ways: 

• To increase the area of the virtual display being viewed, expand both the display 
window and the display viewport proportionately. 

• To decrease the area of the virtual display being viewed, contract both the 
display window and the display viewport proportionately. 

2.6.1 Distortion of Graphic Objects 

The aspect ratio of the virtual display, the display window, and the display viewport 
are the factors that determine whether a graphic object will be distorted when it 
is mapped to the display screen. The display viewport can have any proportions 
width to height that is specified (within the limits of the display device). If the 
proportions of the display viewport do not match the proportions of the display 
window, a stretching or squeezing effect occurs with the graphic object. The exact 
effect depends upon the proportional differences between the viewport and window. 
This happens because the graphics software is trying to make the display window fit 
the display viewport. The transformation of the graphic object affects different types 
of objects in different ways: 

• Straight lines remain straight, but may differ in length and slope, depending 
upon the window size and the coordinate system. 

• Curved lines can change somewhat in shape. The amount and nature of the 
change depends upon the characteristics of the graphic object and the mapping 
(transformation) from display window to viewport. 
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• Arcs change their shape and size. For instance, an ellipse may change its 
proportions. 

• Graphics text (specifically character size and spacing) is not adjusted to fit the 
required number of characters into the display viewport. The size and spacing 
of text characters is fixed and will not distort. However, the starting position of 
the text may change, depending upon the transformation which occurs between 
window and viewport. 

Distortion can be corrected in the following way: 

The application program can create a display viewport whose proportions are 
appropriate for a particular graphics window in world coordinate space. Because 
the display window can have any proportions in world coordinate space, a 
display viewport of the proper proportions for a display window that is square, 
tall and narrow, short and wide, or any other proportions, can be created. 


2.7 Display Lists 

A display list is a device-independent encoding of the exact contents of a virtual 
display. The graphics software maintains and uses display lists to achieve the 
following goals: 

• Allow the automatic management of panning, zooming, resizing, and duplication 
of display windows. 

• Allow the structuring of virtual display objects. 

• Allow objects in a virtual display to be viewed simultaneously within several 
display viewports. 

• Allow the storage and reexecution of UIS pictures 

• Allow editing of UIS pictures 


2.8 Generic Encoding and UIS Metafiles 

Whenever a graphic object is drawn in the virtual display or an attribute is modified, 
an encoded entry of the object or attribute modification is added to the display list. 
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Such entries allow any application to extract arbitrary output from a virtual display, 
give it to an intelligent application or store the data as a generically encoded file or 
buffer known as a metafile, and then later reexecute the generically encoded binary 
stream into a new virtual display. 

Generic encoding is both device independent and self describing. 

When UIS routines are executed, a binary encoded packet of values is constructed 
and stored as display list entries. When the binary encoded packet is extracted from 
the display list used, it becomes a generically encoded UIS metafile. Such metafiles 
can be reexecuted to invoke the appropriate internal generic encoding routines. 

Figure 2-7 Display List Extraction 
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Although many UIS routines have corresponding generic encoding primitives 
there is not necessarily a one-to-one mapping between UIS routines and generic 
encoding routines or between the UIS routine arguments and generic encoding 
routine arguments. 







Chapter 3 

Graphic Objects and Attributes 


3.1 Overview 

This chapter discusses the basic building blocks that are used in constructing graphic 
objects in a virtual display. These basic components are: 

• Text and graphics routines 

• Attributes and attribute modification routines 

• Attribute blocks 

• Segments 

These topics are discussed in greater detail in the following sections of this chapter. 


3.2 Summary 

Text and graphics routines (sometimes called output routines) are the fundamental 
building blocks that an application program uses to create graphic objects. These 
routines are used to specify lines, circles, text, or other graphic objects. The particular 
details (or attributes) of the way a text or graphic object look when it is displayed is 
determined by the attribute block associated with it. 

An attribute block is a group, or set, of attributes. Attributes are values which specify 
various things about the appearance of a text or graphic object. Every text and 
graphics routine used in an application program is required to specify an attribute 
block that it will use. 

Attribute routines are used in an application program to specify or change the current 
value of an attribute associated with an attribute block. The changed attribute value 
affects subsequent text and graphics routines that use the changed attribute block. 

An attribute routine is required to specify which attribute block in the application 
program it is affecting. 
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Application programs are allowed to group associated attribute, graphics and text 
routines together, A group of attribute, graphics and text routines is called a segment. 
Segments provide the program with a convenient way of viewing several attribute, 
graphics and text routines as a single unit. 

An application program can associate graphics and text routines or even entire 
segments with application-specific data. The application program is allowed to store 
data which is application-specific in the generic encoding stream. In this way, if 
a portion of a display screen is copied, stored and then later used (restored) the 
program will be able to associate internal information with the graphic object. 


3.3 Text and Graphics Routines 

Graphics and text routines map objects directly into the virtual display. They can be 
used to create new objects or modify an existing one. Application programs use text 
and graphics routines to draw lines, circles, text, and other graphic objects. They can 
be combined in various ways to form a desired graphic object. 

Each text and graphics routine has two required arguments: one argument that 
specifies the virtual display in which to draw a graphic object, and another argument 
that specifies the attribute block to be used when drawing the graphic object. 

The way that a text or graphics routine draws a graphic object is influenced by 
several factors. One of the major factors which determines the appearance of a 
graphic object is the attributes that are associated with it. 


3.4 Attributes 

Attributes specify the appearance characteristics of graphic objects created by text 
and graphics routines. They are the factors that influence the way a graphic object 
appears on a display device. Color intensity, style, mode, width, and so on, are all 
characteristics that attributes can determine. Once specified, attribute values stay the 
same until explicitly changed. For example, if the line width is decreased, all lines 
drawn are drawn to that thickness unless the line width is changed. If the application 
program increases the line width, all lines are drawn to the same increased thickness 
until the line width is changed again. 

Each type of graphic and text object has a set of unique attributes. For example, 
attributes that affect graphics do not affect text; the opposite is also true. There are, 
however, general attributes that affect all routines. For example the background has 
an attribute that can be set to determine the way the background will appear. The 
background can be thought of as all parts of a display that are not covered by an 
object created by a text or graphics routine. 
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Attributes can be divided into the following general categories: 

• General attributes 

• Text attributes 

• Graphics attributes 

• Window attribute 

These categories are discussed in the following sections of this chapter. 

3.4.1 General Attributes 

General attributes apply to all types of text and graphics routines. General attributes 
include the following kinds of attributes: 

• Writing color 

• Background color 

• Writing mode 

Writing Color 

The writing color attribute assigns the writing color. This attribute is used by all text 
and graphics routines (such as lines, text, etc.). It is expressed by specifying an index 
into a color map. 

Background Color 

This attribute assigns the background color. It is expressed by specifying an index 
into a color map. 

Writing Mode 

This attribute assigns the mode of writing text or graphics. In particular, the writing 
mode determines the exact way that a text or graphics routine will use the writing 
and background colors to display a graphic object. 

3.4.2 Text Attributes 

Font set 

The font set attribute specifies the font set that is used to define text characters. Fonts 
express the size and shape of the characters in physical dimensions. This attribute 
enables text to be displayed in the right size by display routines during text plotting. 
You can choose from a variety of multinational character set fonts and technical 
character set fonts. 
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Character spacing 

The character spacing attribute defines character spacing for width and height of 
character sizes. It is defined as the additional unit of increment beyond the normal 
character size for highly spaced characters. This attribute is specified as a floating¬ 
point number. It is multiplied by the normal character size to produce the actual 
spacing distance. If zeros are specified, then no additional spacing is performed. 
Negative values are also allowed. When used, the spacing is reduced instead of 
increased. Negative values for this attribute can cause the characters to overlap in 
some cases. 

Text Path 

The text path is the direction of text drawing. The text path specification consists of 
two parts—the major path and the minor path. The major path refers to the direction 
in which character are drawn on a line. The minor path refers to the direction used 
for beginning a new line of text. The following table lists the major path and minor 
path available. 

• Left to right (default major text path) 

• Right to left 

• Bottom to top 

• Top to bottom (default minor text path) 

Text Slope 

Text slope represents the angle between the actual path of text drawing and the 
major text path. The actual path of text drawing connects the baseline points of each 
character cell. 

Text Margins 

The text margins attribute specifies a starting margin and the x coordinate distance to 
the ending margin. 

Text Formatting 

The text formatting attribute along with the text margins attribute positions text flush 
against either or both margins, centered, or with no formatting at all. UIS supports 
four types of text formatting modes as follows: 

• Left justification 

• Right justification 

• Center justification 

• Full justification 
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Character Rotation 

Individual characters are rotated counterclockwise from 0 to 360 degrees. The angle 
of rotation is the angle between the baseline vector of the character cell and the 
actual path of the text drawing. 

Character Slant 

The character slant attribute specifies the angle between the character cell's up vector 
and baseline vector. The angle of character slant can be expressed as a negative or 
positive value. 

Character Size 

Character scaling allows you to increase the height and width of characters drawn in 
the virtual display. 

3.4.3 Graphics Attributes 

Graphics attributes, or line attributes, affect graphic objects such as lines, polylines, 
polygons, rectangles, arcs, and curves. They determine the line style and width, and 
control filling of objects, among other things. 

Current Line Drawing Width 

The current line drawing width sets the line width in terms of world or device 
coordinate units. Line width is specified as a floating-point number that is either 
interpreted as a world coordinate width or multiplied with the standard line width 
for a device to produce the desired line width. 

Line Style 

The line style attribute sets the current line style of line routines. It is a bit vector that 
is used to indicate the color of each pixel to be drawn. The color can be designated 
to be either the same as the foreground or the background. The bit vector is repeated 
as many times as necessary to draw all the pixels in the line. 

Fill Pattern 

The fill pattern attribute specifies the fill character to be used for filling closed figures 
such as polygons, circles, and ellipses. The fill pattern is specified as a font file and 
the index of a character in that font file. The pattern defined by the character is used 
to fill the figure. Refer to Appendix D of this manual for further information about 
fill patterns. 
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Arc Type 

The arc type attribute specifies the way an open arc of a circle or ellipse should be 
closed. This attribute can have the following values: 

• Open—when specified as open, the arc is not closed off. 

• Pie—when specified as pie, two radii are drawn from the endpoints of the arc to 
the centerpoint (forming a pie shape). 

• Chord—when specified as chord, a line is drawn between the two endpoints of 
the arc connecting them together. 

3.4.4 Window Attribute 

Clipping Rectangle 

The clipping rectangle is the area of a virtual display that is made available for the 
user to view. The clipping rectangle is specified as the comers of a world coordinate 
rectangle that all drawing operations are clipped to. Objects, or parts of objects, 
outside of the clipping rectangle cannot be viewed. 


3.5 Attribute Blocks 

An attribute block is a set of attribute values that describes the appearance of 
any graphic object that is created by an application program. Each attribute block 
contains attributes for graphics, text, and general display characteristics such as 
writing mode and background and foreground indices. 

There can be up to 256 different attribute blocks addressable at any one time. They 
are addressed by numbers ranging from 0 to 255. Application programs assign and 
use attribute block numbers. 

3.5.1 Attribute Block 0 

Attribute block 0 is a special attribute block that is specified by the graphics software. 
This attribute block contains a standard set of text and graphics attributes. The 
attributes in this block cannot be modified by the application program. Attribute 
block 0 is read only. There is no convention on the naming and usage of attribute 
blocks, with the exception of attribute block 0. This attribute block is reserved by the 
graphics software as a default attribute block. 

Attribute block 0 provides default attribute values that can be used by an application 
program. It also serves as an attribute block template for an application programmer 
to use when creating alternate attribute blocks. 
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3.6 Segments 

A segment is a designated group of attribute block, graphics and text objects. 
Segments allow the application program to use a special attribute without the need 
for knowing which particular attribute blocks are not being used by other parts of the 
program. Another major use of segmentation is to implement transformations either 
on a per-segment basis or on the entire segment tree. This provides convenience for 
the programmer and increased modularity for the program. 

Nested Segments 

Segments can be nested. Each nested segment uses the current set of attribute blocks 
of higher level segments. This makes it simpler to create segments without having to 
redefine attribute blocks. However, modifications of attribute blocks in a segment do 
not affect the attribute blocks of higher level segments. 

Extracting and Reexecuting Segments 

An application program can take the contents of a file containing a display list of a 
virtual display and execute it into another virtual display as a segment. The attributes 
of the original virtual display should not affect the virtual display segment which is 
being inserted. 


3.7 Viewing Transformations 

The viewing transformation is the mapping of the display window to the display 
viewport. The viewing transformation can affect the appearance of a graphic object 
when it is viewed on a display screen. The shapes of the display window and the 
display viewport will affect the way text and graphic objects look when they are 
displayed. 


3.8 Two-Dimensional Geometric Transformations 

Geometric transformations can also alter the way graphic objects are displayed 
through scaling, translation, and rotation. All of these methods involve manipulation 
of the object's angular orientation or shape in the virtual display. 
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Scaling 

The term scaling applies to the proportional expansion or reduction of graphic 
objects on the display screen. For example, if the display window and viewport 
shapes are different in proportion, the graphics software has to squeeze or stretch the 
window to fit the viewport. The distortion of the graphics window causes distortion 
of the graphic objects in that window. Different graphic objects are affected in 
different ways. Refer to Chapter 2 for further information about the distortion of 
graphic objects. 

Translation 

The points that define the position of graphic object in a coordinate system are 
translated when its coordinates are altered without changing its angular relationship 
with other object or the implied angular relationship between the object and the 
coordinate system. For example, two lines are moved in the coordinate system, and 
yet remain parallel. 

Rotation 

When a graphic object turns on a pivotal point or axis, it is rotating. It can rotate 
with respect to some point on its surface, or it can revolve around some external 
point. In order to give the appearance of rotation on the display screen, you must 
first translate the axis of the object to the origin or center of the coordinate system. 
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4.1 Overview 

Depending on the type of VAXstation available to you, you can display graphic 
objects in black-and-white, grey scale, or color. The VAXstation offers you a number 
of color options. However, there are several concepts you should be aware of at the 
outset. This chapter discusses these concepts and the features of the color subsystem 
in the following topics: 

• Color hardware systems 

• UIS virtual color maps 

• Miscellaneous color concepts 

See Chapter 16 for more information about programming in color. 


4.2 Color Hardware Systems 

There are three types of VAXstation hardware systems: (1) monochrome displays 
black and white only, (2) intensity displays shades of gray or achromatic color, and 
(3) color displays shades, tints, hues or chromatic colors. UIS supports all three color 
systems. 


4.3 Raster Graphics Concepts 

The VAXstation display screen consists of a set of picture elements called pixels. 
Pixels are the smallest displayable unit of a graphic object. The rectangular set 
of pixels on the VAXstation screen is a raster. Graphic objects are written by 
illuminating the necessary pixels along the path of points that geometrically describe 
the object. Each pixel has an address and a binary value associated with it. Pixel 
values determine the color of graphic objects. 
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4.3.1 Hardware Interpretation of Pixel Values 

The number of possible pixel values depends on the number of bit planes or planes 
of memory that the system hardware supports. You can think of a plane as an 
allocation of memory where each bit on a plane maps to a pixel on the display 
screen. Conversely, each pixel has an address in memory. The following table 
shows the relationship between the number of planes supported in hardware and the 
number of the possible pixel values. 



Number of 

Number of 

Workstation 

Planes 

Possible Values 

Monochrome 

1 

2 

Intensity or color 

4 or 8 

16 or 256 


Figure 4-1 show how pixel values are represented in single- and multiplane systems. 

Figure 4-1 Bitplane Configuration in Single- and Multiplane Systems 
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In Figure 4-1, a pixel on the VAXstation screen is associated with four corresponding 
bits in memory on each bit plane of a four-plane system. If the bit settings are 
arranged as a binary value corresponding to the high- and low-order planes, they 
would appear in the following order; IOII 2 . 
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Therefore, the pixel value would be lljo- A pixel in a four-plane system can have a 
maximum of 16 values. The pixel value can be used in two different ways, as a direct 
color value or as a mapped color value. 

Direct Color Value 

If the pixel value were used as a direct color value, each of the possible pixel values 
would directly specify a color. In other words, the pixel value would be sent directly 
to system hardware, such as a digital-to-analog converter, and would be used as the 
actual color value of the graphic object. For example, the VAXstation monochrome 
system, which is a one-plane system, interprets pixel values as direct color values 
where 0 is black and 1 is white. 


Figure 4-2 Direct Color Values 
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Mapped Color Value 

When pixel values are interpreted as mapped color values, they indirectly specify an 
actual color value located in a hardware color look-up table or hardware color map. 

The pixel value is an index to an entry in the color map. 
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Figure 4-3 Hardware Color Map 
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The size of the hardware color map is identical to the number of possible pixel 
values and is the maximum number of colors that can be displayed simultaneously. 
Table 4-1 lists the size of the hardware color map in intensity and color systems. 


Table 4-1 Hardware Color Map Characteristics 


System 

Number of 
Planes 

Number of 

Entries 

Intensity 

Four 

16 


Eight 

256 

Color 

Four 

16 


Eight 

256 


Each hardware color map entry contains a color value to be displayed for each 
pixel. Conversely, the value of each pixel is the hardware color map index of a color 
map entry containing the actual color value. The pixel on the VAXstation screen is 
illuminated using this color value. 
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Figure 4-4 Mapped Color Values in Four-Plane System 
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For example, an eight-plane VAXstation intensity or color system has a hardware 
color map with 256 entries. Each color map entry contains color values that are RGB 
color components and that define the desired color. 

4.3.2 Color Representation Models 

Color values are expressed according to the requirements of the particular color 
representation model used. Three well known color representation models are hue 
lightness saturation (HLS), hue saturation value (HSV), and red green blue (RGB). 
The UIS base color model is the RGB model. RGB color values are in the range 0.0 to 
1.0, inclusive. Red, green, and blue color component values comprise a single color 
value on a VAXstation color system. 

Intensity values, the color values associated with shades of gray are specified as a 
single value in the range 0.0 to 1.0, inclusive. Figure 4-5 shows RGB and intensity 
color values as hardware color map entries. 

Figure 4-5 RGB and Intensity Color Values as Hardware Color Map Entries 
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4.3.3 Color Palette 

Your color palette is the number of possible colors that you can specify. Table 4-2 
show the color palette available on each color system. 

Color Palette Size and Direct Color Systems 

On direct color systems, the palette size is identical to the number of simultaneously 
displayable colors. For example, the size of the color palette of a VAXstation 
monochrome system is 2. Only two possible colors, black and white, can be 
displayed simultaneously on the screen. 




Color Concepts 4-7 


Color Palette Size and Mapped Color Systems 

On mapped color systems, the palette size is, typically, much greater than the 
number of the simultaneously displayable colors. The palette size is determined by 
the precision of color components' specification. For example, on VAXstation color 
system, each color component can be specified with eight binary bits of precision for 
each red, green, and blue color components or 2^'* or 16,177,216 possible colors. 


Table 4-2 Color Palette 


System 

Possible 

Colors 

Monochrome 

black and white 

Intensity 

up to 2^“^ shades of gray 

Color 

up to 2 ^^ chromatic colors 


4.4 UlS Virtual Color Maps 

An application that uses hardware color resources, that is, the hardware color map 
must be aware of the hardware system limitations. The application must know the 
color characteristics of the hardware as well. Is the system direct color or mapped 
color? What is the precision of the color representation values for each RGB color 
component? What is the range of possible pixel values? 

The hardware color map contains a finite number of entries—for example, 16 entries 
in a four-plane system. Concurrent processes executing in the same display space 
must somehow share system color resources. 

Why Use Virtual Color Maps? 

The virtualization of the hardware color map solves problems arising from individual 
applications requiring large amounts of system resources. It also solves the problem 
of many processes competing for finite color resources. The use of virtual color 
maps is analogous to the use of virtual memory in a multiprogramming environment 
where many processes must access physical memory. When concurrent processes 
require collectively more color map entries than exist in the hardware color map, 
the color values associated with each competing process are swapped in and out of 
the hardware color map as virtual color maps. Swapping virtual color maps in and 
out of the hardware color map is a means of arbitrating hardware color map use 
across applications. The process of loading or writing values of the virtual color map 
into the hardware lookup table is transparent to the user. Figure 4-6 illustrates the 
swapping of two 16-entry virtual color maps into a 16-entry hardware color map. 
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Applications see only a virtual color map, not the underlying hardware resources. 
Each virtual display has a virtual color map associated with it. 

Characteristics of Virtual Color Maps 

A virtual color map is flexible enough to meet the needs of a wide range of 
applications. Virtual color map size can range from 2 to 32,768 entries. If you do 
not specify a virtual color map, a two-entry virtual color map is created by default. 
The virtual color map size does not have to match that of the hardware color 
map. Although virtual color maps are potentially shareable among applications, 
they are private by default. Virtual color maps can be specified as resident, that is, 
nonswappable in the hardware color map. The following table show how virtual 
color map entries are initialized. 


Virtual Color 


Map Entry 

Color Value 

0 

Default window background color 

1 

Default window foreground color 


All other entries are undefined. 

UIS transparently reconciles differences between the virtual color map model and the 
hardware color resources. UIS manages the concurrent use of these resources across 
applications. 

For information about creating and using virtual color maps, see Chapter 16. 

4.4.1 Reserved Hardware Color Map Entries 

On mapped color systems, due to hardware limitations, the hardware color system 
or the UIS window management software preallocates some of the hardware color 
map entries for special purposes. For example, pointer colors, window background 
and foreground colors, and display screen color are allocated reserved entries in the 
hardware color map. Figure 4-7 describes reserved entries in a hardware color map 
in a four-plane system. 
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Figure 4-7 Reserved Hardware Color Map Entries in a 4-Plane Color System 
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Whenever a virtual color map exceeds the size of the hardware color map less 
the reserved entries, the results are unpredictable. For more information about 
obtaining the hardware color map characteristics using the programming interface, 
see Chapter 16. 
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4.5 UlS Color Map Segments 

The use of color map segments represents a device-specific binding of a virtual color 
map to the underlying hardware color resources, that is, the hardware color map. In 
a color mapped color system, color map segments are bound to specific hardware 
color map entries and swapped in and out of the hardware color map based on 
system and user events. Usually, applications need not worry about color map 
segments. UIS handles the device-specific binding automatically. Applications may 
want to use color map segments for the following reasons: 

• Applications can control explicitly the binding of the virtual color map and the 
hardware color map. 

• Applications are not transported to different hardware configurations, for 
example, four-plane to eight-plane systems or VAXstation color and intensity 
systems to VAXstation monochrome systems. 


4.6 Shareable Virtual Color Maps 

By default, virtual color maps are private. Yet, they may be shared among 
cooperating application programs to define a uniform color regime and to conserve 
hardware color map entries. Shared virtual color maps have names, an ASCII string 
from 1 to 15 characters and a name space (UIC group or system). For example, UIS 
uses a system-wide, shared color map to display terminal emulator windows and the 
window and screen menus. 


4.7 Miscellaneous UIS Color Concepts 

The following sections contain additional information about the UIS color subsystem. 

4.7.1 standard and Preferred Colors 

VAXstation color and intensity systems supports two sets of symbolically defined 
colors. Workstation standard colors and intensity values are a set of colors used 
for specific purposes within the workstation environment. For example, the default 
window background and foreground, cursor background and foreground colors, and 
the display screen color are the workstation standard colors. 

Workstation preferred colors are a set of colors representing the user's preference 
for the eight combinations of the RGB primary colors. For example, workstation 
preferred colors are used to define a particular shade of red, rather than a full 
intensity red. In an intensity system, preferred colors may be used to define a base 
white level from which preferred shades of gray are derived. Preferred values are 
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simply a mechanism for conveniently maintaining and communicating a user's color 
preferences to an application. 

Values for standard and preferred colors are set using the workstation setup 
mechanism. Standard and preferred color and intensity values can be returned 
using UIS$GET_WS_COLOR and UIS$GET_WS_1NTENS1TY. 

4.7.2 Monochrome, Intensity, and Color Compatibility Features 

Two types of calls are provided to change or retrieve color map entries. 
UIS$SET_COLOR and UIS$SET_INTENSITY both load a single color value in a 
color map entry. Both routines can be used in any of the three hardware color 
environments—monochrome, intensity, or color. 


Color 

System 

Compatibility 

Feature 

Monochrome 

UIS chooses the color (black or white) closest to the color specified 
by the application. 

Intensity^ 

UIS$SET_COLOR converts the specified RGB values to an equivalent 
gray level using an equation. 

UIS$SET_1NTENSITY sets the requested gray level directly. 

Color^ 

UIS$SET_COLOR sets the requested RGB color values directly. 
UIS$SET_1NTENSITY converts the specified intensity value to an 
equivalent RGB value using an equation. 

^The color-to-intensity equation is 7 = 0.30R + 0.59G + 0.1 IB. Color television broadcasts transmitted for 
reception by noncolor television sets are processed in this manner. 

^The intensity-to-color equation is R = I, G = I, B = I. 


4.7.3 Color Value Conversion 

Routines are provided to convert color values in applications using other color 
representation models. 

• Hue lightness saturation (HLS) 

• Hue saturation value (HSV) 

In both models, hue values are specified from 0.0 to 360.0, inclusive, where red = 0.0. 
Values for lightness, saturation, and value are between 0.0 and 1.0, inclusive. 
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4.7.4 Set Colors and Realized Colors 

UIS routines that set or load color map entries in the virtual color map accept 
F_floating point values between 0.0 and 1.0, inclusive. The precision of the F_floating 
point data type is approximately seven decimal places. 

The precision for the color representation for a particular device may not be enough 
to represent accurately the requested F_floating point value. 

In this case, the set color value (F_floating) differs from the realized color value 
(device precision). An application can determine realized color values using 
UIS$GET_COLOR(S) and including the optional parameter. See Chapter 16 for 
details. 

4.7.5 Color Regeneration Characteristics 

Color regeneration is a hardware characteristic that specifies whether changing a 
color map entry affects the color of existing graphic objects (retroactive regeneration) 
or only graphic objects drawn after the color map is changed (sequential 
regeneration). 

The following table summarizes regeneration characteristics of direct and mapped 
color systems. 


System 

Regeneration Characteristics 

Direct color 

Usually sequential 

Mapped color 

Usually retroactive 


An application can determine the hardware color regeneration characteristics by 
calling UIS$GET_HW_INFO. 
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5.1 Overview 

This chapter discusses the devices that enable user and application program 
interaction. Some of the topics covered in this chapter are: 

• Pointing devices 

• Virtual keyboards 

• Physical keyboards 

5.1.1 VAXstation Input Devices 

Application programs and users interact through input devices. The types of input 
devices that a VAXstation typically utilizes are: 

• Keyboard 

• Mouse 

• Tablet 

The keyboard allows you to initiate program interaction and respond to application 
program prompts by pressing a key or entering data. The mouse and tablet let you 
communicate with an application program by pointing to objects or items with a 
pointer and by making selections with buttons. 
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5.2 Pointers 

There are two types of pointing devices that can be used with the workstation, a 
mouse and a tablet. The workstation supports the use of only one pointing device at 
a time. 

Application programs receive input from a pointing device by either polling or 
soliciting interrupts. To do this, programs use pointer input routines. Because only 
one pointer input device can be used at a time, applications use the same set of 
pointer input routines to get input from either the mouse or the tablet. The actual 
pointer input device being used is transparent to an application. 

The programming interface lets you set the pattern or the position of the cursor that 
is synchronized with the pointing device. 

5.2.1 Mouse 

The mouse is a small hand-held device with three buttons on the top and a roller-ball 
on the bottom. Associated with the mouse, on the display screen, is an arrow-shaped 
cursor (or pointer). 

The user is able to manipulate items on the display screen by the combined use of 
the mouse-controlled pointer and the mouse buttons. By moving the mouse in any 
direction on a flat surface, the ball on the bottom is turned, causing the pointer on 
the screen to move. In this way, the pointer can be moved in any direction and 
placed at any desired position on the display screen. By pressing the buttons on the 
mouse, the user can select items in a menu and perform a variety of other functions. 

The mouse is a relative pointing device. The mouse reports only its relative movement 
to the workstation. The mouse can be picked up and placed in different position 
without any change in the position of the pointer on the screen. Consequently, 
the workstation keeps track of the current mouse position, only when the mouse is 
moved on a surface. 

Some of the ways that application programs can use the pointer are as follows: 

• To create menus from which the user selects items 

• To read the position of the pointer and the state of the mouse buttons 

The workstation human interface implements menus that allow users to create, 
select, move, and delete objects on the display screen. Application programs can 
create menus that do the same things. To select a menu item, the user moves the 
pointer to the region of the desired item and presses one of the mouse buttons. The 
application program predefines items and specifies the action to be taken when the 
user selects an item. 
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Application programs can detect when the pointer is moved across the boundary of 
a window or a mouse button is pressed within a window. Programs can also read 
the current pointer location and current button state. When the pointer is moved to 
the border, or outside, of a screen viewport, the human interface detects interrupts 
from the mouse. If the pointer is positioned inside of a viewport that is mapped to 
an application-created window, the application program can receive these interrupts. 

5.2.2 Tablet 

The tablet is an optional input device that can be used with the workstation. Tablets 
operate in much the same way as a mouse. An application program uses the same 
routines to receive information from a tablet as it does for the mouse. This is possible 
because the actual physical input device being used is transparent to an application 
program. 

The tablet is an absolute pointing device. That is, it reports all movement to the 
workstation. For example, if the pen or stylus is picked up and moved to another 
position on the tablet, the pointer will change its position on the screen to match the 
movement. 

A tablet is composed of the following parts: 

• Tablet 

• Puck 

• Stylus 

Tablet 

The tablet is a flat square device with a surface similar to a table top. It is used in 
conjunction with a puck and/or stylus to locate points on the display screen. When 
the puck and/or stylus are moved on the surface of the tablet, the pointer on the 
display screen moves in an identical fashion. If you pick up the puck and place it 
in different region of the tablet, the pointer on the display screen would reflect this 
change. The tablet has a grid that senses a change in the position of the pen or 
stylus. 

Puck 

The puck is a hand-held device which is moved on the tablet to locate points on the 
display screen. The puck has cross-hair markings used for precision in positioning 
it on the tablet. It also has four buttons which can be used for various purposes, 
depending upon the application. 
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Stylus 

The stylus is a hand held device which resembles a pen. It is moved on the tablet 
to locate points on the display screen. The stylus has greater precision than the 
puck in locating positions. The stylus can also have buttons, usually one is located 
on the outside of the barrel and one on the tip. The functions of these buttons are 
application specific. 


5.3 Keyboards 

It is important to be able to distinguish between a physical keyboard (the workstation 
keyboard) and a virtual keyboard (a simulated keyboard). 

The physical keyboard is the actual workstation keyboard. You can press its keys 
to respond to prompts from the application program, or you can type and enter 
data into the currently active display window. The workstation can have only one 
physical keyboard attached to it at any one time. 

A virtual keyboard is a conceptual keyboard that does not have an actual physical 
existence. Rather, a virtual keyboard is a simulated keyboard that exists in software 
and is associated with a display window. Each application may have one or more 
virtual keyboards attached to it. Virtual keyboards provide the means for applications 
to share the single physical keyboard. 

5.3.1 Virtual Keyboards 

A virtual keyboard is not an actual physical keyboard; but instead can be considered 
a simulated keyboard. Virtual keyboards are conceptual in nature and exist only 
in software. Virtual keyboards have much the same relationship to the physical 
keyboard as virtual displays have to the physical display screen. 

Application programs can read from the physical (workstation) keyboard, assign the 
physical keyboard to a display window, and modify the characteristics of a physical 
keyboard associated with a window. Programs are able to do this by means of 
virtual keyboard routines. These routines can establish one or more virtual keyboards. 
They enable applications to manipulate the workstation keyboard by referring to the 
established virtual keyboards. 

You can think of virtual keyboards in the following way. The VAXstation supports 
multiple windows with multiple processes running simultaneously. Normally, these 
windows and processes require keyboard input at various times. Therefore, each 
window may need to have a keyboard associated with it. Consequently, there is 
a need for several keyboards (one for each window). Because there is only one 
physical keyboard available, it must be shared among several windows. The way 
that this is done is through the concept of virtual keyboards. 
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Virtual keyboards provide a way for each window to have its own keyboard. There 
can be one, or several, display windows and virtual keyboards active on the display 
screen at one time. However, the physical keyboard can be connected to only one 
virtual keyboard at a time. A virtual keyboard can be attached to more than one 
display window at a time; however, each display window may have only one virtual 
keyboard attached to it. 

The user has control over the association between the physical keyboard and the 
various virtual keyboards that exist at any point in time. A user can connect the 
workstation keyboard to different windows by manipulating the display viewports 
to which the virtual keyboards are connected. The user determines which window 
the workstation keyboard is attached to, and in that way, which process is receiving 
keyboard input. In this way, the user determines which window on the screen is 
currently active. 

When the user switches the keyboard between windows, the workstation gives 
notification of which window has the keyboard. It places a small KB icon in the 
upper right comer of all windows that are able to use the keyboard. The KB icon 
is highlighted in the window that is currently active. An application can restrict 
windows from receiving keyboard input. Display windows that do not interact with 
the keyboard will not have the KB icon. 




PART II How to Program with MicroVMS 
Workstation Graphics 




Chapter 6 

Programming Considerations 


6.1 Overview 

The User Interface Services (UIS) graphics software package allows you to create 
application programs that call system routines. Using UIS system routines, you can 
create virtual displays, display windows, viewports, graphic images, and text. These 
callable routines can be accessed through high-level programming languages as well 
as VAX MACRO and VAX BLISS. The programming examples used in succeeding 
chapters to illustrate the capabilities of the UIS graphics software are written in VAX 
FORTRAN. This chapter discusses the following topics; 

• Calling UIS routines 

• Argument characteristics 

• Constants 

• Condition values 

• Additional program components 

• Program execution 

Refer to the MicroVMS Programming Support Manual for additional information about 
other callable routines. 


6.2 Calling UIS Routines 

Your application programs must contain references or calls to specific UIS system 
routines to draw and manipulate graphic images and text. These CALL statements 
and language-specific function declarations invoke the UIS system routines through 
the VAX Procedure Calling Standard. 
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6.2.1 Calling Sequences 

The format of a call to UIS, or the calling sequence, consists of the elements that 
make up the statement and their positional order. Refer to Tables A-1 and B-1 in the 
appendices for summaries of UlS and UlSDC calling sequences, respectively. 

6.2.1.1 Call Type 

Calls to UIS system routines from application programs, typically specify the function 
name and an argument list as follows: 

vd_id=UIS$CREATE_DISPLAY(-1.0.-1.0,+1.0,+1.0,width,height) 

However, some UIS routines are functions and return values to the calling program. 
The preceding example shows such a call from a VAX FORTRAN program. It 
also returns a value, the virtual display identifier, to the vd_id argument. Such 
return values are stored in variables that are often arguments (where applicable) in 
subsequent routine calls. 

UIS routines that are not functions must be called using an explicit VAX FORTRAN 
CALL statement. 

CALL UIS$PL0T(vd_id,l,-1.0,-1.0) 

There is no standard call type used by all programming languages to invoke the 
UIS system routines. This manual does not attempt to describe the ways in which 
each high-level programming language calls a UIS system routine but uses VAX 
FORTRAN as an example of a typical call syntax. For specific information about 
calling syntax, please refer to the appropriate language user's guide. 

6.2.1.2 Routine Name 

You must identify the system routine you are calling by specifying its routine name, 
for example, UIS$MOVE_AREA. The routine name consists of a symbol prefix 
identifying the system facility (UIS$) and the symbol name indicating what operation 
it performs (MOVE—AREA). The routine name is also known as the entry point name. 

6.2.1.3 Argument List 

The argument list is the list of parameters to be passed to the UIS routine. This 
list, typically, follows the function name as a parenthetical expression containing 
arguments separated by commas. You can substitute your own argument names in 
place of the formal parameter names. However, whenever you invoke a UIS routine, 
you must maintain the positional order of the parameters in the argument list. The 
following example illustrates positional order of the parameters: 

CALL UISSCIRCLE(VD_ID,ATB,CENTER.X,CENTER.Y,XRADIUS.START.DEG,END.DEG) 
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6.3 Argument Characteristics 

Because the arguments in your routine call are the means of passing data to the 
called routine, you should keep in mind the characteristics of arguments—VMS 
Usage, type, access, mechanism. 

6.3.1 VMS Usage 

The VMS Usage entry contains the name of a VMS data type that has special meaning 
in the VMS operating system environment. 

The VMS Usage entry is NOT a traditional data type such as the VAX standard 
data types byte, word, longword and so on. It is significant only within the context 
of the VMS operating system environment and is intended solely to expedite data 
declarations within application programs. 

Refer to Appendix A in the MicroVMS Workstation Version 3.0 Release Notes for a 
complete listing of VMS usage entries and implementation charts for each VAX 
language supported by UIS. The implementation charts describe how to code the 
VMS usage entry in the programming language of your application. 


6.3.2 Type 

The type characteristic refers to the standard data type of the argument, that is, 
whether the argument is a word, longword, floating point number, and so forth. 
Depending on the programming language you are using, you may be required to 
declare certain data types locally within your program. These locally declared data 
structures provide data type definitions for the arguments in subsequent calls to UIS 
routines. 

6.3.2.1 VAX Standard Data Types 

When a calling program passes an argument to a system routine, the routine expects 
the argument to be of a particular data type. The routine descriptions in Part III 
indicate the expected data types for each argument. 

Properly speaking, an argument does not have a data type; rather, the data specified 
by an argument has a data type. The argument is merely the vehicle for the passing 
of data to the called routine. 

Nevertheless, the phrase "argument data type" is frequently used to describe the data 
type of the data that is specified by the argument. This terminology is used because 
it is simpler and more straightforward than the strictly accurate phrase "data type of 
the data specified by the argument." 
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The following table contains the data types allowed by the VAX Procedure Calling 
Standard. 


Table 6-1 VAX Standard Data Types 


Data Type 

Symbolic Code 

Absolute date and time 

DSC$K-DTYPE-ADT 

Byte integer (signed) 

DSC$K-DTYPE-B 

Bound label value 

DSC$K-DTYPE-BLV 

Bound procedure value 

DSC$K-DTYPE-BPV 

Byte (unsigned) 

DSC$K-DTYPE-BU 

COBOL intermediate temporary 

DSC$K-DTYPE-CIT 

D_floating 

DSC$K-DTYPE-D 

D_floating complex 

DSC$K-DTYPE-DC 

Descriptor 

DSC$K-DTYPE-DSC 

F_floating 

DSC$K-DTYPE-F 

F_floating complex 

DSC$K-DTYPE-FC 

G—floating 

DSC$K-DTYPE-G 

G—floating complex 

DSC$K-DTYPE-GC 

H—floating 

DSC$K-DTYPE-H 

H—floating complex 

DSC$K-DTYPE-HC 

Longword integer (signed) 

DSC$K-DTYPE_L 

Longword (unsigned) 

DSC$K-DTYPE-LU 

Numeric string, left separate sign 

DSC$K-DTYPE-NL 

Numeric string, left overpunched sign 

DSC$K-DTYPE-NLO 

Numeric string, right separate sign 

DSC$K-DTYPE-NR 

Numeric string, right overpunched sign 

DSC$K-DTYPE-NRO 

Numeric string, unsigned 

DSC$K_DTYPE-NU 

Numeric string, zoned sign 

DSC$K-DTYPE-NZ 

Octaword integer (signed) 

DSC$K-DTYPE-0 

Octaword (unsigned) 

DSC$K-DTYPE-OU 

Packed decimal string 

DSC$K-DTYPE-P 

Quadword integer (signed) 

DSC$K-DTYPE-Q 

Quadword (unsigned) 

DSC$K-DTYPE-QU 

Character string 

DSC$K-DTYPE-T 

Aligned bit string 

DSC$K-DTYPE-V 

Varying character string 

DSC$K-DTYPE-VT 
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Table 6-1 (Cont.) VAX Standard Data Types 


Data Type 

Symbolic Code 

Unaligned bit string 

DSC$K_DTYPE_VU 

Word integer (signed) 

DSC$K_DTYPE_W 

Word (unsigned) 

DSC$K_DTYPE_WU 

Unspecified 

DSC$K_DTYPE_Z 

Procedure entry mask 

DSC$K_DTYPE_ZEM 

Sequence of instruction 

DSC$K_DTYPE_ZI 


Refer to the MicroVMS Programming Support Manual for more information about VAX 
standard data types. 

6.3.3 Access 

The access characteristic describes how a calling routine will use the data specified by 
the argument. Following is a list of the most common types of argument access: 

• Read only access—the UIS routine uses the data specified by the argument as 
input only. 

• Write only access—the UIS routine uses the argument as a location to return data 
only. 

• Modify access—the UIS routine uses the data specified by the argument as input 
for its operation and then writes data to that argument. 

6.3.4 Mechanism 

VAX language extensions provide the means of reconciling the different argument 
passing mechanisms within a programming language. The VAX Procedure Calling 
Standard provides three ways by which all application programs may pass arguments 
to a system routine. 

• By value—the argument contains the actual data to be used by the routine, the 
actual data is said to be passed to the routine by value. 

• By reference—the argument contains the address of the location in memory of 
the actual data to be used by the routine, the actual data is said to be passed to 
the routine by reference. 
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• By descriptor—the argument contains the address of a descriptor, the actual data 

is said to be passed by descriptor. 

A descriptor consists of two or more longwords (depending on the type of 
descriptor used) that describe the location, length, and data type of the data to be 
used by the called routine. 

All language processors, except VAX MACRO and VAX BLISS, pass arguments 
by reference or descriptor by default. Some high-level languages including VAX 
FORTRAN set up the descriptors and arrays for you. 

The following list contains the passing mechanisms allowed by the VAX Procedure 
Calling Standard. 


Passing Mechanism 

Descriptor Code 

By value 


By reference 


By reference, array reference 


By descriptor 


By descriptor, fixed-length 

DSC$K_CLASS_S 

By descriptor, dynamic string 

DSC$K_CLASS_D 

By descriptor, array 

DSC$K_CLASS_A 

By descriptor, procedure 

DSC$K_CLASS_P 

By descriptor, decimal string 

DSC$K_CLASS_SD 

By descriptor, noncontiguous array 

DSC$K_CLASS_NCA 

By descriptor, varying string 

DSC$K_CLASS_VS 

By descriptor, varying string array 

DSC$K_CLASS_VSA 

By descriptor, unaligned bit string 

DSC$K_CLASS_UBS 

By descriptor, unaligned bit array 

DSC$K_CLASS_UBA 

By descriptor, string with bounds 

DSC$K_CLASS_SB 

By descriptor, unaligned bit string 1 with bounds 

DSC$K_CLASS_UBSB 


Refer to the MicroVMS Programming Support Manual for more information about 
passing mechanisms. 
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6.3.4.1 VAX FORTRAN Built-In Functions 

VAX FORTRAN also supports explicit argument passing mechanisms, or built-in 
functions that do not require formal data declarations. Built-in functions are specified 
only in the argument list of the call (with one exception) and are used when data 
must be passed to a subroutine written in a programming language other than VAX 
FORTRAN. The four VAX FORTRAN built-in functions are as follows: 

• %VAL—specifies that the argument must be passed as a value. 

• %REF—specifies that the argument must be passed as the address of the actual 
data. 

• %DESCR—specifies that the argument must be passed as the address of a 
descriptor that points to the actual data. 

• %LOC—returns the virtual address of the actual data. 

The built-in function %LOC can be used outside an argument list to obtain 
the address of a variable. For example, %LOC can be used in an assignment 
statement where a longword in a character string descriptor is assigned the 
address of the actual character string. 

By default, VAX FORTRAN passes numeric data by reference and character string 
data by descriptor. The built-in functions override default argument passing 
mechanisms. Occasionally, an external procedure is encountered that passes data 
differently from the VAX FORTRAN default and, in such cases, the built-in functions 
can be used in VAX FORTRAN code. 

For specific information regarding similar procedure argument passing mechanisms 
for other high-level programming languages, refer to the appropriate language user's 
guide. 

Figure 6-1 illustrates how arguments are placed on the stack and shows how 
arguments are passed to the called routine. 
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Figure 6-1 Passing Arguments 
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6.4 UlS Constants 

UIS constants are symbolic names for values that can be passed to, or returned from, 
UIS routines. UIS constants are syntactically equivalent to literal integer constants 
and are used in the following ways: 

• As arguments to UIS functions 

• As indexes into array arguments that are passed to, or received from, the UIS 
subsystem 

• As literals with which you can compare a returned value from an inquiry routine 
Refer to Section 6.6 for information about UIS symbol definition files. 


6.5 Condition Values Signaled 

Occasionally hardware- or software-related events occur indicating errors that could 
jeopardize successful program execution. Instead of returning condition values to 
RO (as in VAX MACRO) or to a status variable (as in high-level languages), the UIS 
routines signal a condition. In such cases, unless you have explicitly arranged to 
handle the signaled condition, program execution terminates. 


6.6 Additional Program Components 

In addition to the usual program entities, you should be aware of UlS-spedfic and 
language-specific program components that affect program execution. 

Subroutines and Functions 

VAX FORTRAN application programs must declare subroutines as external 
procedures with the EXTERNAL statement if the subroutine name is used as 
an actual argument to other subprograms. The subprogram can then use the 
corresponding dummy argument in a function reference or a CALL statement. 

Entry Point and Symbol Definition Files 

All UIS and UISDC routines are declared in an entry point file supplied with the 
graphics software. In addition, you may need to include a file of UIS symbol 
definitions depending on the language you are using. These files are also known 
as data description files. See your appropriate language user's manual to determine 
whether you must include these files in your program data declarations. 
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The following table contains a list of entry point files and symbol definition files for 
each VAX programming language. All files are located in SYS$LIBRARY. 


Table 6-2 Entry Point and Symbol Definition Files 


VAX Language 

Entry Point File 

Symbol Definition File 

BLISS 

UISENTRY.R32 

U1SUSRDEF.R32 

C 

UISENTRY.H 

UISUSRDEF.H 

FORTRAN 

UISENTRY.FOR 

UISUSRDEF.FOR 

MACRO 


UlSUSRDEF.MAR 

PASCAL 

UISENTRY.PAS 

UISUSRDEF.PAS 

PL/I 

UISENTRY.PLI 

UlSUSRDEF.PLI 


Message Definition File 

A language-specific message definition file called UISMSG is included in the directory 
SYS$LIBRARY. All possible UIS error codes are defined in this file. It is similar to 
the entry point file UISENTRY. For instance, to define message symbols in a VAX 
FORTRAN condition handler, you would add the following line to your program. 

INCLUDE ’SYS$LIBRARY:UISMSG’ 

The appropriate language version of UISMSG is copied to your disk during the 
installation procedure depending on the programming language options you select. 

All messages symbols use the prefix UIS$_ 


6.7 Notes to Programmers 

As a programmer, you should know about language-specific issues that might affect 
program execution. It is recommended that all application programmers read this 
section. 

6.7.1 VAX C Programmers 

Entry Point and Symbol Definition Files 

The file UISENTRY.H defines all routine entry points in lowercase characters, while 
UISUSRDEF.H defines all constants in uppercase characters. 
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6.7.2 VAX PASCAL Programmers 

Entry Point Files 

Because VAX PASCAL references arguments as formal parameters, your calls to UIS 
must specify the same parameter names as those contained in the entry point file 
UlSENTRY.PAS. Therefore, specify obj_ld as the argument whenever the routine 
descriptions in Parts 111 and IV allow a choice between the obj_id and seg_id 
arguments. Refer to Tables A-1 and B-1 for summaries of UIS and UlSDC calling 
sequences. 

Creating Environment Files 

Before running application programs written in VAX PASCAL, you must perform the 
following procedure. 

1. Set your default directory to SYS$LIBRARY. 

$ SET DEFAULT SYS$LIBRARY 

2. Produce an environment file of symbolic definitions and type declarations 
by invoking the VAX PASCAL compiler with the /ENVIRONMENT and 
/NOOBJECT qualifiers. 

$ PASCAL/ENVIRONMENT/NOOBJECT UISENTRY 

The result of the compilation is UISENTRY.PEN, an environment file. 

3. Include the INHERIT attribute in the first line of the application program or 
program module specifying UISENTRY.PEN. 

[INHERIT(’UISENTRY.PEN’)] 

4. Repeat this procedure for the symbol definition file UlSUSRDEF.PAS. 

Refer to Programming in VAX PASCAL for more information about the /ENVIRONMENT 
and /NOOBJECT qualifiers and the INHERIT attribute. 

Drawing Lines and Polygons 

VAX PASCAL application programs should use UIS$PLOT_ARRAY rather than 
UIS$PLOT and UIS$LINE—ARRAY instead of UIS$LINE, when drawing lines and 
polygons. 
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6.7.3 VAX PL/I Programmers 

Entry Point Files 

Because VAX PL/I references arguments as formal parameters, your calls to UIS 
must specify the same parameter names as those contained in the entry point file 
UISENTRY.PLI. Therefore, specify obj_id as the argument whenever the routine 
descriptions in Parts III and IV allow a choice between the obj_id and seg_id 
arguments. Refer to Tables A-1 and B-1 for summaries of UIS and UISDC calling 
sequences. 


6.8 Programming Examples 

The programming examples in Parts II and III of this manual use VAX FORTRAN 
Version 4.4. In addition, some examples particularly in Part III include ellipses, the 
standard convention for indicating portions of code that have been left out. The 
ellipses are also included to point out places in the program where code could be 
added at the programmer's discretion. 

Many of the examples include the VAX FORTRAN PAUSE statement. The PAUSE 
suspends program execution and returns the user to the DCL prompt ($). A default 
message "FORTRAN PAUSE" is returned to the display screen. The graphic images 
that were created on the display screen will remain. You can respond to the DCL 
prompt ($) by typing one of the following commands: 

• CONTINUE—Program execution resumes at the next executable statement. 

• EXIT—Program execution is terminated. 

• DEBUG—Program execution resumes under the control of the VAX/VMS 
Symbolic Debugger. 

NOTE: If your program is running in batch mode, program execution is not 
suspended. All messages are written to the system output file. 

6.8.1 Structure of Programming Tutorial 

Part II attempts to describe UIS graphics features and programming using a tutorial 
approach in each chapter. Within each chapter, after a discussion of the main topics, 
you are offered two types of information under the following headings: 

• Programming options — Lists the features that you can use at a given point in 
time. The addition of each new group of programming options lets you progress 
in an orderly fashion from simple programming tasks to relatively complex ones. 
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• Program development — Lists the current programming objective and the tasks 
needed to successfully implement the objective. 

Program — Contains the source module with embedded callouts. Each 
callout refers to a programming feature that should be noted. 

Program output — Displays and explains the output from the program. 

Each programming example uses some or all of the programming options listed. Not 
all routines are illustrated in the accompanying example. 

6.9 Program Execution 

Your program can run in batch mode with predefined data or it can run interactively 
accepting input from you when needed. However, in order to execute your 
application program successfully, you must first store it as a file using a text editor. 
Invoke the text editor on your workstation using the following command sequence. 
Please refer to appropriate sections of the user's manual for detailed information 
about Micro VMS text editors. 

$ EDIT MYPROG.FOR 

Please note in the previous example that you must supply a file name, for example, 
MYPROG. In addition, a VAX FORTRAN file type (FOR) is added to the file name to 
identify the file as a VAX FORTRAN source file. Enter your program according to the 
rules of the programming language you are using. Refer to the appropriate language 
reference manual for detailed information about the language. 

6.9.1 Compiling Your Program 

The newly created source file MYPROG.FOR must be compiled prior to execution. 
The language compiler, in our case the VAX FORTRAN compiler, checks for proper 
syntax and initiates code optimization where appropriate. Invoke the language 
compiler in the following manner. 

$ FORTRAN/LIST MYPROG 

Note that the file type need not be included. By default, the system searches for 
the latest version of the file, MYPROG, with a file type of FOR. If the application 
source file contains syntax errors, you will receive compile-time error messages 
called diagnostics. These diagnostic messages indicate the portion of code in error as 
well as an explanation. The /LIST qualifier specifies the creation of a listing file of 
accounting information and diagnostics (if present). 

Some language compilers return a predetermined maximum number of diagnostics 
before terminating compilation. In any case, you must correct these errors and 
resubmit the source program for a successful compilation. Successful compilation 
produces an object module with file type of OBJ. 
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6.9.2 Linking the Object Module 

The Linker resolves references to subroutines and allocates memory to variables 
within your program. Invoke the Linker in the following manner; 

$ LINK MYPROG 

You need not specify the file type of the program, MYPROG. By default, the system 
searches for the latest version of the file MYPROG with the file type OBJ. 

In addition, you can link object modules of programs written in different source code. 

6.9.3 Running the Executable Image 

The Linker produces an executable image with a file type of EXE. At this point, you 
can run your program. However, you may receive run-time errors in which case you 
must correct errors in your source code and recompile the source module and relink 
the object modules. Run the executable image after receiving the $ prompt in the 
following manner: 

$ RUN MYPROG 
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7.1 Overview 

This chapter describes how to create basic graphic objects: lines, circles, ellipses, and 
text. To accomplish this task you will need to know about the following topics: 

• Creating a virtual display 

• Creating graphics and text 

• Creating a display window 

You will construct an interactive program that contains the necessary components 
for creating graphic objects. Later, you will manipulate these displays using other 
windowing routines. 

Refer to Section 6.8 for more information about the programming examples that 
appear in this manual. 


7.2 Step 1—Creating a Virtual Display 

When an artist paints a picture, he is concerned with presenting a subject from a 
particular perspective. He then wonders how he will frame his subject and how 
much space he will need to accomplish this task successfully. These needs are 
fulfilled by the size of the canvas he chooses. All of the objects that we will create 
will use such a frame of reference or virtual display to establish the universe in which 
our graphic objects will exist. 

While the artist simply chooses a spot on the canvas to paint, our calls to UIS 
routines must reference points within our virtual display. The UIS subsystem uses 
the coordinates you specify to generate a coordinate system with which we can create 
the virtual display and subsequent windows. This coordinate system, or grid, allows 
us to reference points as world coordinates along two perpendicular axes labelled x 
and y. 
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Unlike the artist's canvas which has finite dimensions, your virtual display is infinite 
and graphic objects may be drawn anywhere in it. 

7.2.1 Specifying Coordinate Values 

Many routines documented in this manual require specifying coordinates to define 
virtual displays, display windows, and extent rectangles. Table 7-1 lists information 
about coordinate values. 


Table 7-1 Types of Coordinates 


Coordinate 

Units 

Data 

Type 

Origin 

Absolute 

cm 

F_fIoating^ 

Lower-left corner of 
display screen or tablet 

Normalized 

Gutenbergs 

F_floating^ 

Lower-left corner of 
virtual display 

Viewport-relative 

Pixels 

Longword (unsigned) 

Lower-left corner of 
display viewport 

World 

User-specified 

F—floating^ 

Lower-left corner of 
virtual display 

^ F_floating point numbers may be expressed with up to approximately 

seven decimal digits of precision. 


7.2.2 Programming Options 

The following options allow you to create the basic structures used to create graphic 
objects. 

Creating a Virtual Display 

You must use UIS$CREATE—DISPLAY to specify the world coordinate space in 
which you will draw graphic objects. The world coordinate values specified in 
UIS$CREATE—DISPLAY establish mapping and scaling factors that the system may 
later use in viewport creation. The coordinate values should not be thought of as the 
absolute boundaries of the virtual display. 

You can create an unlimited number of virtual displays subject to system and process 
resources. 

Deleting a Virtual Display 

You may delete a virtual display at any time in your program using UIS$DELETE— 
DISPLAY. However, you should remember that when you delete a virtual display 
you are throwing out the canvas on which you have drawn graphic objects. 
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7.2.3 Program Development 

Programming Objectives 

To create an executable program using the VAX FORTRAN programming language. 

Programming Tasks 

1. Create a virtual display. 

2. Delete the virtual display. 

PROGRAM IMAGES.1 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ O 
INCLUDE ’SYS$LIBRARY:UISUSRDEF’ Q 


VD_ID=UIS$CREATE_DISPLAY(+1.0.+1.0.+20.0,+20.0,10.0,10.0) © 


PAUSE O 

CALL UIS$DELETE.DISPLAY(VD_ID) © 

END 

At this point the program contains UlS entry points O and definitions ©. It also 
includes a call ® to UIS$CREATE—DISPLAY. The plus sign ( + ) is optional for 
positive coordinates. The minus sign (-) is required for negative coordinates. 

Because world coordinates are f—floating numbers, the decimal point is required 
when specifying world coordinate pairs. 

See Section 6.8 for information about the VAX FORTRAN PAUSE statement O. 

U1S$DELETE—DISPLAY is called © to remove the virtual display before the program 
ends. Terminating an application program with UIS$DELETE—DISPLAY is not 
required. 

Besides specifying the world coordinate range of the virtual display, U1S$ CREATE— 
DISPLAY returns the value of the virtual display identifier in vd—id. The virtual 
display ID uniquely identifies this newly created virtual display and is used in 
subsequent windowing routines. Typically, UIS$CREATE—DISPLAY is the first UIS 
routine to be called in an application program. 

If your application program were to invoke the UIS$CREATE—DISPLAY only, you 
would not notice a change in your workstation display screen. 
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7.3 Step 2—Creating Graphics and Text 

You are now at a point comparable to the artist preparing to draw on the canvas. 
The virtual display is an infinitely large canvas. You must choose the types of 
graphic objects to be drawn there. You can draw graphic objects anywhere in the 
virtual display. Three types of graphic objects can be drawn in the virtual display as 
shown in the following table. 


Graphic Object 

Example 

Geometric shapes 

Point, line, polygon, circle, and ellipse 

Text 

Characters 

Raster images 

Any object constructed with a bitmap of varying size 


7.3.1 Graphics Drawing Operations 

The following considerations apply to graphics operations: 

• All line drawing operations are symmetrical and include both end points. 

• All region specifications include the borders of the region specified. This applies 
in all cases to fill patterns, images, ellipses, moving windows, and so forth. 

7.3.2 Programming Options 

You can draw any of the graphic objects listed in this section. Read the routine 
description of each routine carefully. 

Creating Points, Lines, and Polygons 

Depending on the number of times you repeat coordinate pairs in UIS$PLOT or 
UlS$PLOT_ARRAY, you can draw a point, connected lines, or a polygon. 

You can draw more than one unconnected line in single call to UIS$LINE or 
U1S$LINE—ARRAY. Each pair of world coordinate pairs specified represents the 
end points of a line. 

NOTE: VAX PASCAL application programs should use UIS$PLOT_ARRAY or 
U1S$LINE—ARRAY to draw all lines, disconnected lines, and polygons. 

Creating Circles 

You can create circles or circular arcs with UIS$C1RCLE. 


Creating Ellipses 

You can create ellipses or elliptical arcs with UIS$ELL1PSE. 
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Drawing Images 

You can create a bitmap image of a graphic object and then draw the raster to the 
display screen with UIS$IMAGE using the following procedure: 

1. Create a data structure in your program, such as an array or record, that defines 
the bitmap. 

2. Set the bits in the structure to create the bitmap image by assigning values to the 
elements of the structure. 

3. Specify width and height of the raster image in pixels in UIS$IMAGE. 

4. Specify the name of the data structure in UIS$IMAGE. 

Figure 7-1 illustrates how bitmap settings are mapped to raster images. 


Figure 7-1 Mapping a Bitmap to a Raster 
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Mapping the raster image occurs from left to right and from top to bottom. See the 
UIS$IMAGE routine description for more information. 


Text 

You can set the current position and create text anywhere within a virtual display 
using UIS$TEXT. The text within a virtual display could be used for labelling 
an accompanying graphic object within the window. Only UIS$TEXT can write 
characters in a virtual display. 
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7.3.3 Program Development 

Programming Objectives 

To create an executable program using the VAX FORTRAN programming language. 
Programming Tasks 

1. Create a virtual display. 

2. Draw four graphic objects in the virtual display. 

3. Delete the virtual display. 

PROGRAM IMAGES_2 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE >SYS$LIBRARY:UISUSRDEF’ 

REAL WIDTH.HEIGHT 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0.20.0.20.0,10.0,10.0) 

CALL UIS$CIRCLE(VD_ID.O,10.0,10.0,1.0) O 
CALL UIS$PL0T(VD_ID.0.4.0.3.0,5.0,7.0) © 

CALL UIS$ELLIPSE(VD_ID,0,15.0,15.0.1.0,2.0) © 

CALL UIS$TEXT(VD_ID.O,’This is a test.’.1.0.12.0) O 


PAUSE 

CALL UIS$DELETE_DISPLAY(VD_ID) 

END 

In the preceding example, world coordinate pairs are specified explicitly to the UIS 
graphics routines O © © O describing the exact locations of the graphic objects 
(circle, line, ellipse, and text) in the virtual display. 

If you executed the program in its present form, the workstation display screen 
would show no objects. Your calls to the UIS graphics and text routines have been 
processed. However, you must create a window to view what has been drawn. 


7.4 Step 3—Creating a Display Window 

The next step is to create a display window. The display window defines the world 
coordinate range of the viewable portion of the virtual display. When you create a 
display window, you are also creating a display viewport, an area on the physical 
screen on which the display window is mapped. 
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7.4.1 Programming Options 

All the programming options available to us at this point, are provided through 
UIS$CREATE—WINDOW. At this point, you do not need to know about its full 
capabilities, which are discussed in more detail in the next chapter. 

Creating a Display Window and Viewport 

You can create a display viewport and its associated viewport with 
UIS$CRE ATE -WINDOW. 

7.4.2 Program Development 

Programming Objectives 

To create an executable program that draws and displays graphic objects on the 
VAXstation display screen. 

Programming Tasks 

1. Create a virtual display. 

2. Draw four graphic objects in the virtual display. 

3. Create a display window and viewport. 

4. Delete the virtual display. 

PROGRAM IMAGES_2A 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYSSLIBRARY:UISUSRDEF’ 

REAL*4 WIDTH.HEIGHT 

TYPE *.’ENTER DESIRED VIEWPORT WIDTH AND HEIGHT’ 

ACCEPT *.WIDTH,HEIGHT 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,20.0.20.0,WIDTH,HEIGHT) O 

CALL UIS$CIRCLE(VD_ID,0.10.0,10.0,1.0) © 

CALL UIS$PL0T(VD_ID.0,4.0.3.0.5.0.7.0) © 

CALL UIS$ELLIPSE(VD_ID,0,15.0,15.0.1.0,2.0) O 

CALL UIS$TEXT(VD_ID.O,’This is a test.’.1.0,12.0) © 

WD_ID=UIS$CREATE_WIND0W(VD_ID,’SYS$W0RKSTATI0N’) © 

PAUSE 

CALL UIS$DELETE_DISPLAY(VD_ID) 

END 
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The world coordinate range of the virtual display and the default dimensions of the 
display viewport are specified in a call to UIS$CREATE—DISPLAY O. 

NOTE: The display viewport will not be mapped until a display window is created. 

Next the graphics and text routines are called 0 0 O 0 to draw the graphic objects. 

A display window and viewport are created in a call to UIS$CREATE—WINDOW 0. 
The world coordinate range of the window and the viewport width and height are 
not specified. Therefore, the world coordinate space of the display window, that is, 
the viewable portion of the virtual display defaults to the entire virtual display. You 
will see all objects drawn in the virtual display. 

7.4.3 Calling UlSSCIRCLE, UIS$ELLIPSE, UIS$PLOT, UIS$TEXT, 
and UIS$CREATE_WINDOW 

When you run the program IMAGES—2A, you should get a single display viewport 
without a title, containing text, a circle, a line, and an ellipse as shown in Figure 7-2. 

Figure 7-2 Display Viewport and Graphic Objects 
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Chapter 8 

Display Windows and Viewports 


8.1 Overview 

Before you begin to manipulate graphic objects, you need to know more about 
display windows and viewports. After all, display windows and viewports allow 
you to see graphic objects drawn in the virtual display. This chapter discusses the 
following topics: 

• Creating display windows and viewports 

• Moving display windows 

• Manipulating display viewports 

• Deleting display windows 

• Erasing the virtual display 

• Creating transformations 

These tasks are accomplished by the UIS windowing routines. 

8.2 Windowing Routines 

Windowing routines are responsible for the creation and deletion of virtual displays, 
display windows, and display viewports. Table 8-1 provides a list of window 
routines and their functions. 
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Table 8-1 UIS Windowing Routines 


Routine 

UIS$CREATE-DISPLAY 

UIS$CREATE_WINDOW 

UIS$EXPAND_ICON 

UIS$MOVE_AREA 

UIS$MO VE -WINDOW 

UIS$POP-VIEWPORT 

UIS$PUSH-VIEWPORT 

UIS$SHRINK-TO-ICON 

UIS$CREATE_TRANSFORMATION 

UIS$ERASE 

UIS$DELETE_DISPLAY 

UIS$DELETE_WINDOW 


Description 

Creates a virtual display and defines default viewport 
dimensions 

Creates display window and viewport 
Substitutes an associated viewport for an icon 

Moves a specified rectangle and its contents in the 
virtual display to another part of the virtual display 

Pans the display window across the virtual display 
Allows an occluded viewport to be fully displayed 
Places a viewport behind another viewport 
Substitutes an icon for a display viewport 
Alters the world coordinate space of the virtual display 

Erases objects that lie completely within a specified 
rectangle in the virtual display 

Deletes a virtual display 

Deletes a display window and viewport 


These routines allow you to create and manage the display screen environment 
and to perform certain housekeeping functions such as erasing and deleting virtual 
displays and windows. 


8.3 Step 1 —Creating Many Display Windows 

For every display window that you create, you are also creating a display viewport. 
A one-to-one relationship exists between each display window and its associated 
viewport. An application program can create an unlimited number of display 
windows and viewports subject to system and process resources. 

8.3.1 Programming Options 

Each display window can be unique with regard to world coordinate range. 
Therefore, you can create display viewports that are also unique with respect to 
dimensions and position in the display screen. 
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Display Window Size 

By default, a newly created display window displays the full world coordinate space 
specified when creating the virtual display. You can specify world coordinates pairs 
in UIS$CREATE—WINDOW as you see fit to produce display windows of different 
proportions within the virtual display. 

Display Viewport Size 

Similarly, the default display viewport dimensions are equal to the values specified 
in the width and height arguments in the UIS$CREATE—DISPLAY call. However, 
you may specify different dimensions to scale the contents of the window. Maximum 
display viewport size depends on the dimensions of the display screen. If you 
specify viewport dimensions that exceed the size of the display screen, UIS scales the 
viewport to the size of the display screen. 

Graphic Object Magnification 

The world coordinate range of the display window or the dimensions of the display 
viewport can be manipulated to increase or decrease magnification of the object 
displayed in the viewport. This occurs when the display window area is decreased 
or increased while the viewport size remains the same, or when the viewport is 
decreased or increased while dimensions of the window remain the same. 

Distortion 

Distortion occurs whenever the aspect ratios of the display viewport and display 
window are not equal. The aspect ratio of the display window is the absolute value 
of the difference between y world coordinates of the upper-right and the lower-right 
corners of the window divided by the absolute value of the difference between the 
X world coordinates of the lower-right and lower-left corners. Figure 8-1 illustrates 
how to calculate the aspect ratios of the display window and viewport. 

Figure 8-1 Aspect Ratios of the Display Window and Display Viewport 

|y1-y0| viewport height 

I x1 - xO I viewport width 
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Number of Windows and Viewports 

You can create an unlimited number of display windows and, as a result, an 
unlimited number of display viewports subject to system and process resources. 
In addition, you can specify the dimensions of each display viewport. 
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Display Banner 

The display banner appears along the top border of the display viewport and 
contains the menu and keyboard icons as well as the viewport title. The maximum 
length of the viewport title is 63 characters. 

You can suppress the generation of the display banner with the attributes argument 
in UIS$CREATE—WINDOW. When the display banner is suppressed, only the 
viewport border is displayed. 

Display Viewport Placement 

You can either explicitly place a display viewport on the workstation display screen 
or you can allow UIS to choose a location for you. By default, display viewport 
placement is random. 


8.3.2 Program Development 

Programming Objectives 

To create four display windows and display viewports. 

Programming Tasks 

1. Create a virtual display. 

2. Draw four graphic objects in the virtual display. 

3. Create four display windows and viewports omitting the display window 
coordinates in the calls to UIS$CREATE—WINDOW. 

4. Delete the virtual display. 

PROGRAM IMAGES_3 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,20.0,20.0,10.0,10.0) 

CALL UISSCIRCLE(VD_ID,0,10.0,10.0,1.0) 

CALL UIS$PL0T(VD_ID,0,4.0,3.0,5.0,7.0) 

CALL UIS$ELLIPSE(VD_ID,0,15.0,15.0,1.0,2.0) 

CALL UIS$TEXT(VD_ID,0,’This is a test.’,1.0,12.0) 

WD_ID1=UIS$CREATE_WIND0W(VD.ID,’SYS$W0RKSTATI0N’ ) O 
PAUSE 

WD_ID2=UIS$CREATE_WIND0W(VD_ID,’SYS$W0RKSTATI0N’) © 
WD_ID3=UIS$CREATE_WIND0W(VD_ID,’SYS$W0RKSTATI0N’) © 
WD_ID4=UIS$CREATE_WIND0W(VD_ID,’SYS$W0RKSTATI0N’) O 
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PAUSE 

CALL UIS$DELETE_DISPLAY(VD_ID) 

END 

Four calls to U1S$CREATE—WINDOW O O O O have been inserted to create 
four windows. The world coordinate range of each window defaults to the world 
coordinate range of the entire virtual display. 

8.3.3 Calling UIS$CREATE_WINDOW 

If you were to run this program now, your workstation screen would display the 
graphic objects as shown in Figure 8-2. 
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Figure 8-2 Four Display Viewports 
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As you can see, four display windows have been created and mapped to the 
display screen as four viewports. Each of the viewports contains four objects. 
Because display window world coordinate pairs were not explicitly specified in 
UIS$CREATE—WINDOW, the viewports allow you to see the entire area of the 
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virtual display by default. In addition, because the display viewport width and 
height in centimeters were not explicitly specified in the UIS$CREATE—WINDOW 
call, each display viewport is, by default, 10 cm square as specified in the width and 
height arguments of the UIS$CREATE—DISPLAY call. 


8.4 Step 2—Deleting and Erasing Display Windows 

Some windowing routines perform housekeeping functions, that is, they delete 
unused display windows or erase graphic objects from the virtual displays. Such 
routines are important in managing display environment, when you run complicated 
applications. 

8.4.1 Programming Options 

You may want your application program to delete unwanted windows, viewports, 
and virtual displays. This can be done by calling UIS routines for deleting and 
erasing display windows and virtual displays. 

Display Window Deletion 

Any display window can be deleted without interfering with other windows or 
viewports. Deletion of the display window does not affect the graphic objects 
in the virtual display. If you delete a display window, you are also deleting the 
associated display viewport. Delete any display window and its associated viewport 
by specifying the appropriate display window identifier in UIS$DELETE—WINDOW. 

Erasing the Virtual Display 

Graphic objects that lie completely within a specified rectangle in the virtual display 
can be deleted at any time using UIS$ERASE. If no rectangle is specified, the entire 
virtual display is used. 

8.4.2 Program Development 

Programming Objectives 

To enclose each graphic object in its own display window and then to delete a 
window and its viewport. 
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Programming Tasks 

1. Create a virtual display. 

2. Draw four graphic objects in the virtual display. 

3. Create four display windows and viewports specifying display window regions 
that enclose each of the graphic objects. 

• Specify display window regions that enclose each of the graphic objects. 

• Specify a viewport title identifying the graphic object. 

4. Delete one of the display windows and its viewport. 

PROGRAM IMAGES_4 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYSSLIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL WIDTH.HEIGHT 

TYPE ’ENTER DISPLAY SIZE’ O 
ACCEPT *.WIDTH.HEIGHT 

VD_ID=UIS$CREATE_DISPLAY(1.0.1.0.20.0.20.0.WIDTH.HEIGHT) 

CALL UISSCIRCLE(VD.ID.0.12.0.12.0.1.0) 

CALL UIS$PL0T(VD.ID.0.4.0.3.0.5.0.7.0) 

CALL UIS$ELLIPSE(VD_ID.0.15.0.15.0.1.0.2.0) 

CALL UIS$TEXT(VD_ID.O.’This is a test.’.1.0.12.0) 

WD_ID1=UIS$CREATE_WIND0W(VD.ID.’SYS$W0RKSTATI0N’.’CIRCLE’. 

2 10.0.10.0.14.0.14.0.WIDTH.HEIGHT) © 

WD.ID2=UIS$CREATE.WIND0W(VD.ID.’SYS$W0RKSTATI0N’.’LINE’. 

2 3.0.2.0.6.0.8.0.WIDTH.HEIGHT) © 

WD.ID3=UIS$CREATE.WIND0W(VD.ID.’SYS$W0RKSTATI0N’.’TEXT’. 

2 1.0.12.0.10.0.10.0.WIDTH.HEIGHT) O 

WD.ID4=UIS$CREATE.WIND0W(VD.ID.’SYS$W0RKSTATI0N’.’ELLIPSE’. 

2 13.0.13.0.17.0.18.0.WIDTH.HEIGHT) © 

PAUSE 

CALL UIS$DELETE.WIND0W(WD.ID2) © 

PAUSE 

END 

The program now accepts input for the display viewport dimensions interactively O. 

The world coordinate space that defines each display window is specified explicitly 
in the U1S$CREATE-WINDOW calls © © O ©. 
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UIS$CREATE—WINDOW returns the variable ivd—idl, the display window identifier 
@ to uniquely identify the LINE window. Note that the call to delete the LINE 
window © references this variable, 

8.4.3 Calling UIS$DELETE_WINDOW 

If we ran this program until the first PAUSE statement, the workstation screen would 
display the graphic objects shown in Figure 8-3. 
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Figure 8-3 Objects Within Different Windows 
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By specifying explicitly a particular world coordinate range within the virtual display 
for each display window, each graphic object lies within a separate window that 
maps to the physical display screen as a separate display viewport. 
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To continue program execution, type CONTINUE at DCL prompt ($). The program 
continues to execute and the screen changes as shown in Figure 8-4. 

Figure 8-4 Display Window Deletion 
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The viewport LINE and its window are deleted. However, the actual graphic 
object still exists. You have simply deleted the display window that allowed you 
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to view the portion of the virtual display that contained the line. If you called 
UIS$ CREATE—WINDOW again, specifying the appropriate world coordinate space 
in the virtual display, the object would reappear. 


8.5 Step 3—Manipulating Display Windows and Viewports 

Display viewports and windows do not have to remain as static objects on your 
screen. You can manipulate the newly created display windows and viewports in 
many ways. 

8.5.1 Programming Options 

Viewport placement features and window attributes are implemented using the 
optional attributes argument of UIS$CREATE—WINDOW. 

NOTE: When you include the attributes argument in UIS$CREATE—WINDOW, 
you are not modifying attribute block 0. 

Attributes and attribute block 0 are discussed in detail in the next chapter. 

General and Exact Placement of Viewports 

Unless you specify otherwise, your display viewports are placed randomly 
throughout the screen. You can move any display viewport to any position on the 
screen. When you create the window, you can specify general viewport placement, 
that is, within a certain vicinity on the screen—top, left, right, or bottom. 

Exact placement positions your display viewport where you want on the screen and 
allows you to occlude other viewports to save space. 

Panning and Zooming the Virtual Display 

You can pan across the virtual display to include either the entire virtual display or 
any discrete area within it. 

Pushing and Popping Display Viewports 

Pushing and popping display viewports is useful when you have created display 
windows with the exact placement attribute. In such a case, your application may 
have created two windows and purposely occluded one of the viewports. In this 
instance, you know which viewport will be occluded and the use of UIS$POP— 
VIEWPORT is clearly indicated. 

Otherwise, the UIS subsystem places newly created windows randomly on the 
display screen by default. As a result, you will not know where the viewports will 
be placed. Therefore, use of UIS$POP_VIEWPORT or UIS$PUSH-VIEWPORT in 
this instance, would be unnecessary and confusing. 
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Moving a Display Viewport 

You can move an existing display viewport anywhere on the display screen using 
UIS$MOVE_VIEWPORT. 

Moving a Portion of the Virtual Display 

You can draw a graphic object in a portion of the virtual display, then move that 
coordinate space to another part of the same virtual display with UIS$MOVE_ 
AREA. The vacated source area is filled with the current background color. 


8.5.2 Program Development I 

Programming Objectives 

To delete three display windows and viewports and then to pan the virtual display 
using the remaining display window. 

Programming Tasks 

1. Create a virtual display. 

2. Draw four graphic objects in the virtual display. 

3. Create four display windows and viewports each containing a graphic object. 

4. Specify a title for each viewport. 

5. Delete three of the four display windows. 

6. Pan the virtual display with the remaining display window using 
UIS$MOVE_WINDOW. 

PROGRAM IMAGES_5 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL WIDTH.HEIGHT 

TYPE *.’ENTER VIEWPORT WIDTH AND HEIGHT’ 

ACCEPT *.WIDTH.HEIGHT 

VD_ID=UIS$CREATE_DISPLAY(1.0.1.0.20.0.20.0.10.0.10.0) 

CALL UIS$CIRCLE(VD_ID.O.12.0.12.0.1.0) O 
CALL UIS$PL0T(VD_ID.0.4.0.3.0.5.0.7.0) © 

CALL UIS$ELLIPSE(VD_ID.0.15.0.15.0.1.0.2.0) @ 

CALL UIS$TEXT(VD_ID.O.’This is a test.’ .1.0.12.0) O 
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WD_ID1=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’,’CIRCLE’. 

2 10.0.10.0.14.0.14.0.WIDTH.HEIGHT) 0 

WD_ID2=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’.’LINE’. 

2 3.0.2.0.6.0.8.0.WIDTH.HEIGHT) O 

WD_ID3=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’.’TEXT’. 

2 1.0.12.0.10.0.10.0.WIDTH.HEIGHT) O 

WD_ID4=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’.’ELLIPSE’. 

2 13.0.13.0.17.0.18.0,WIDTH.HEIGHT) © 

PAUSE ® 

CALL UIS$DELETE_WIND0W(WD_ID1) ® 

CALL UIS$DELETE_WIND0W(WD_ID3) © 

CALL UIS$DELETE_WIND0W(WD_ID4) © 

PAUSE © 

CALL UIS$MOVE_WINDOW(VD_ID.WD_ID2.6.0.8.0.18.0.18.0) © 

PAUSE © 

CALL UIS$DELETE_DISPLAY(VD_ID) 

END 

The program IMAGE _5 creates four graphic objects O © © O in the virtual display. 

The program prompts for the viewport width and height which overrides the values 
specified in UIS$CRE ATE-DISPLAY. 

Each graphic object is contained within a newly created display window © © © ©. 
Each display window is mapped to the physical screen as a display viewport with an 
appropriate title describing the graphic object within the window. 

Program execution is suspended ©. The display screen contains four viewports as 
previously described. 

Three calls to UIS$DELETE—WINDOW © © © remove the windows and their 
viewports CIRCLE, ELLIPSE, and TEXT from the display screen. 

Program is suspended ®, The display screen contains one display viewport LINE. 

A call to UIS$MOVE—WINDOW © has been inserted. Thus, the display window 
LINE pans the virtual display. 
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8.5.3 Calling UIS$MOVE_WINDOW 

The display screen initially contains all four windows as shown in Figure 8-5. 

Figure 8-5 Before Panning the Virtual Display 
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Three of the display windows and viewports are deleted. 

The display viewport LINE remains. Originally, the viewport contained a line; now it 
contains the circle and the ellipse. The display window will go to the location in the 
virtual display you have specified. You may include as many calls to UIS$MOVE_ 
WINDOW as you see fit. Your workstation screen will display the objects shown in 
Figure 8-6. 
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Figure 8-6 Panning the Virtual Display 
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The circle and the ellipse still exist in the virtual display. 


8.5.4 Program Development II 

Programming Objectives 

To demonstrate exact placement of the display viewport on the display screen in 
order to pop and push viewports. 


Programming Tasks 


1. Create a viewport attributes data structure specifying viewport placement data. 

2. Create a virtual display. 

3. Draw two graphic objects in the virtual display in separate viewports. 

4. One viewport will occlude the other initially. 

PROGRAM IMAGES_6 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYSSLIBRARY:UISUSRDEF’ 

REAL WIDTH.HEIGHT 


STRUCTURE/PLACE/ O 


INTEGER*4 
REAL*4 
INTEGER*4 
REAL+4 
INTEGER+4 
END STRUCTURE 


CODE.l 

ABS_P0S_X 

C0DE_2 

ABS_P0S_Y 

END_OF_LIST 


RECORD /PLACE/PLACE_LIST.ON_TOP © 

PLACE.LIST.C0DE_1=WDPL$C_ABS_P0S_X 

PLACE_LIST.ABS_P0S_X=8 0 

PLACE.LIST.C0DE_2=WDPL$C_ABS_P0S_Y 

PLACE_LIST.ABS_P0S_Y=8 O 

PLACE.LIST.END_OF.LIST=WDPL$C_END_OF_LIST 

ON.TOP.C0DE_1=WDPL$C_ABS.P0S_X 
0N_T0P.ABS_P0S_X=8.5 @ 

ON.TOP.C0DE.2=WDPL$C.ABS_P0S_Y 

ON.TOP.ABS_P0S.Y=8.5 0 

ON.TOP.END_OF.LIST=WDPL$C_END_OF_LIST 


TYPE *,'ENTER DISPLAY SIZE’ 
ACCEPT *,WIDTH.HEIGHT 


VD.ID=UIS$CREATE.DISPLAY(1.0.1.0,20.0,20.0.10.0.10.0) 
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CALL UIS$CIRCLE(VD_ID,0.10.0,10.0,1.0) 

CALL UIS$PLOT(VD_ID.0.4.0.3.0.5.0,7.0) 

WD_ID1=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’.’CIRCLE’, 
2 8.0,8.0.12.0,12.0,WIDTH.HEIGHT.PLACE_LIST) O 

WD_ID2=UIS$CREATE_WIND0W(VD_ID.’SYS$W0RKSTATI0N’.’LINE’. 

2 3.0,2.0.6.0.8.0...0N_T0P) ® 

PAUSE ® 

CALL UIS$P0P_VIEWP0RT(WD_ID1) ® 


PAUSE 

CALL UIS$PUSH_VIEWP0RT(WD_ID1) <D 
PAUSE 

CALL UIS$DELETE_DISPLAY(VD_ID) 

END 

A data structure argument O is created and given the symbolic name PLACE 
using the STRUCTURE statement. The symbolic names for the fields were chosen 
arbitrarily. 

Two variables, PLACE—LIST and ON—TOP, of type PLACE are created © and 
contain five longwords. 

Actual values are assigned to the different fields of the record PLACE—LIST. In this 
case, the absolute coordinates of the lower-left corner ® O of the display viewport 
LINE are assigned to the fields ON—TOP.ABS—POS—X and ON—TOP.ABS—POS—Y 
© 0. The absolute coordinates of the display viewport CIRCLE, are assigned to the 
fields PLACEMENT.ABS-POS_X and PLACEMENT.ABS-POS-Y as well. 

Also, the position of your calls to UIS$CREATE—WINDOW © 0 within your 
program is important. The call to create the display viewport CIRCLE must be 
executed prior to LINE. 

At the first PAUSE statement 0, viewport LINE occludes viewport CIRCLE. 

UIS$POP-VIEWPORT is called ©. The display viewport CIRCLE is placed over the 
viewport LINE. 

A call to UIS$PUSH—VIEWPORT 0 returns the viewports to their orginal position. 
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8.5.5 Calling UIS$POP_VIEWPORT and UIS$PUSH_VIEWPORT 

Initially, the viewport LINE is placed over CIRCLE. Note that display viewports 
are placed on the physical display screen with absolute coordinates. The lower-left 
corner of any viewport is the origin of the viewport rectangle. When you request 
exact placement of a viewport, you are specifying where on display screen the origin 
of the viewport rectangle is to be placed relative to the lower-left corner of the 
display screen. 

The program execution is suspended at the first PAUSE statement. The display 
screen contains the graphic objects shown in Figure 8-7. 
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Figure 8-7 Occluding a Display Viewport 
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The display viewports LINE and CIRCLE exchange positions when the call to 
UIS$POP_VIEWPORT is executed. The viewport CIRCLE now occludes LINE as 
shown in Figure 8-8. 


Figure 8-8 Popping a Display Viewport 
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In order to return the viewports to their original positions, a call to UIS$PUSH_ 
VIEWPORT pushes viewport CIRCLE behind viewport LINE as shown in Figure 8-9. 

Figure 8-9 Pushing a Display Viewport 
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8.5.6 Program Development III 

Programming Objectives 

To place a viewport in a general vicinity on the display screen and to create a display 
viewport with no border. 


Programming Tasks 

1. Create a viewport attributes list to hold the appropriate viewport placement and 
attributes data. 


2. Create a virtual display. 

3. Draw two graphic objects in the virtual display. 

4. Create two display windows and associated viewports each containing a graphic 
object. 

5. Delete the virtual display. 

PROGRAM IMAGES.? 

IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL WIDTH.HEIGHT 


STRUCTURE/PLACE/ 


INTEGER*4 

INTEGER*4 

INTEGER+4 

INTEGER*4 

INTEGER*4 


C0DE_5 

REL.POS 

C0DE_6 

ATTR 

ENDQF.LIST 


END STRUCTURE 


RECORD /PLACE/LOCATION(2) © 

LOCATION(1).C0DE_5=WDPL$C_PLACEMENT 

LOCATION(1).REL_POS=WDPL$M_TOP .OR. WDPL$M_LEFT © 

LOCATION(1).C0DE_6=WDPL$C_ATTRIBUTES 

LOCATION(1).ATTR=WDPL$M_NOMENU_ICON 

LOCATION(1).END_OF_LIST=WDPL$C_END_OF_LIST 

LOCATION(2).C0DE_5=WDPL$C_PLACEMENT 

LOCATION(2).REL_POS=WDPL$M_RIGHT .OR. WDPL$M_B0TT0M O 

LOCATION(2).C0DE_6=WDPL$C_ATTRIBUTES 

LOCATION(2).ATTR=WDPL$M_NOBORDER 

LOCATION(2).END_OF_LIST=WDPL$C_END_OF_LIST 


TYPE *,’ENTER VIEWPORT WIDTH AND HEIGHT’ 
ACCEPT WIDTH.HEIGHT 


VD_ID=UIS$CREATE_DISPLAY(1.0.1.0.20.0.20.0.10.0.10.0) 
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CALL UISSCIRCLE(VD_ID,0.12.0.12.0,1.0) 

CALL UIS$ELLIPSE(VD_ID.0,15.0.15.0.1.0.2.0) 

WD_ID1=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’.’CIRCLE’. 

2 10.0,10.0,14.0,14.0,WIDTH.HEIGHT.LOCATION(l)) 

WD_ID4=UIS$CREATE_WIND0W(VD_ID,’SYS$WORKSTATION’.’ELLIPSE’, 

2 13.0.13.0,17.0.18.0,WIDTH.HEIGHT,LOCATION(2)) 

PAUSE 

CALL UIS$DELETE_DISPLAY(VD_ID) 

PAUSE 

END 

The name of the data structure argument PLACE is defined using the STRUCTURE 
statement O. An array LOCATION is defined to have two elements that are records 
with a structure defined by the structure PLACE 0. Each record LOCATION(l) and 
LOCATION(2) consists of two pairs of longwords terminated by a longword equaling 
the constant WDPL$C_END_OF_LIST. 

We prefer to have the display viewport CIRCLE placed in the upper-left corner of 
the display screen and the borderless viewport ELLIPSE in the lower-right corner. 
Therefore, we must specify in each assignment two preference masks for each 
viewport 0 O. 

NOTE: Note that you must use the logical operator .OR. when specifying more 
than one preference mask. 

The array name LOCATION is added to the argument lists of the viewport CIRCLE 
and ELLIPSE to invoke the optional attribute list. 

8.5.7 Requesting General Placement and No Border 

General display viewport placement works best on an uncluttered display screen. 
Your workstation screen will display the objects shown in Figure 8-10. 
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8.5.8 Program Development IV 

Programming Objectives 

To move graphic objects within the virtual display. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Draw two graphic objects in the virtual display. 

4. Move the coordinate space containing each graphic object to another portion of 
the virtual display using UlS$MOVE__AREA. 

PROGRAM AREA 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYSSLIl 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0.50.0,50.0.15.0.15.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’,’MOVE AREA’) 

CALL UIS$PL0T(VD_ID.0.1.0.25.0.16.0,25.0,9.0,42.0,1.0,25.0) O 

CALL UIS$CIRCLE(VD_ID,0,35.0,35.0,10.0) Q 

PAUSE 

CALL UIS$M0VE_AREA(VD_ID,0.0,22.0,20.0,42.0,30.0,1.0) © 

CALL UIS$M0VE_AREA(VD_ID,25.0,25.0,50.0,50.0.1.0,1.0) O 

PAUSE 

END 

A triangle and a circle are drawn in the upper half of the virtual display using 
UIS$PLOT and U1S$CIRCLE O ©. 

A rectangular area containing the triangle is moved to the lower-right area of the 
virtual display ©. A rectangular area containing the circle is moved to the lower-left 
region in the virtual display O. 
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Figure 8-11 Moving Graphic Objects Within the Virtual Display 
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8.5.9 Calling UIS$MOVE_AREA 

Figure 8-11 shows how areas within the virtual display containing graphic objects 
can be moved to other parts of the same virtual display. 


8.6 World Coordinate Transformations 

Certain applications may require that you create more than one virtual display, or 
world coordinate space. Depending on the requirements of the program, you might 
have to map graphic objects in one virtual display to another virtual display, 

8.6.1 Programming Options 

To illustrate the advantages of world coordinate transformations, we will construct 
a program that creates a virtual display. We will then create a circle in a virtual 
display. The circle will be written to new world coordinate space or transformation 
space. 

Two-Dimensional Transformation and Scaling 

Depending on the values supplied to UIS$CREATE—TRANSFORMATION, graphic 
objects mapped to other coordinate spaces may be scaled. If the coordinates of the 
new transformation space are the same as those of the original virtual display, no 
scaling occurs. 

8.6.2 Program Development 

Programming Objectives 

To transform a world coordinate space by altering its mapping and scaling factors. 
Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Draw a graphic object in the virtual display, 

4. Create a new coordinate space using UIS$CREATE—TRANSFORMATION. 

5. Redraw the graphic object substituting the transformation identifier of the new 
coordinate space returned by UIS$CREATE—TRANSFORMATION for the virtual 
display identifier of the old coordinate space. 
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PROGRAM TRANS 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY» 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(-5.0,-5.0.25.0,25.0,10.0,10.0) O 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’.’TRANSFORMATION’) 
CALL UIS$CIRCLE(VD_ID.0.6.0,6.0,7.0) O 

TR_ID=UIS$CREATE_TRANSFORMATION(VD_ID.-5.0,-5.0, 

2 17.5.17.5) @ 

CALL UIS$CIRCLE(TR_ID.0,6.0.6.0,7.0) O 

PAUSE 

END 

The virtual display O and the new transformation space ® specify different 
coordinate ranges. The circles are created in calls to UIS$CIRCLE © O where 
the tr_id argument is substituted for vd—id in the second call. The same circle is 
redrawn with the same world coordinates in the new transformation space. 


8.6.3 Calling UISSCREATE^TRANSFORMATION 

The graphic objects appear to be superimposed one over the other. If the vdxl and 
vdyl arguments are manipulated, the size of the arc can increase or decrease relative 
to the size of the first circle. In any case, the arc is mapped to the transformation 
space eliminating the need for additional computation and coding on the part of the 
programmer. 



Display Windows and Viewports 


8-31 


Figure 8-12 World Coordinate Transformations 
























Chapter 9 
General Attributes 


9.1 Overview 

Until the information presented in this manual has been concerned with UIS output 
routines that create the basic structures needed to produce graphic objects. However, 
there are other types of routines. This chapter discusses the following topics: 

• Understanding general attributes 

• Using general attributes 

The attribute routines place a great deal of control over the quality of graphic objects 
and text in the hands of the programmer. 


9.2 Attributes—How to Use Them 

As the canvas gradually fills with various shapes and figures, the artist is concerned 
not only with the shapes of the subjects—a line, a circle, an ellipse, and text but also 
with whether their appearance conveys the intended meaning. What our artist would 
regard as an aesthetic consideration, we will call an attribute. Attributes control the 
appearance of graphic objects and text. You will use attributes whenever you need 
to enhance some element on the display screen. Attributes can be modified at any 
time within your program. 
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9.2.1 Attribute Blocks 

All UIS attributes are grouped in a data structure called an attribute block. One or 
more attributes may be modified within a given attribute block. Default attribute 
settings reside in attribute block 0. Table 9-1 lists the categories of attributes within 
attribute block 0. 


Table 9-1 Attribute Block 0 


Type 

Attribute 

General 

Writing mode 


Writing color index 


Background color 

Text 

Character rotation 


Character spacing 


Character slant 


Character size 


Text path 


Text slope 


Text formatting 


Left margin 


Right margin 


Font 

Graphics 

Line width 


Line style 


Fill pattern 


Arc type 

Windowing 

Clipping rectangle 


The default attribute settings in attribute block 0 can never be modified. 
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9.2.2 Modifying General Attributes 

When you modify general attributes, you do not change the default attribute settings 
within attribute block 0 itself. You should think of attribute block 0 as a template 
of default settings and you are modifying a copy of this attribute block for use 
within your program. Attribute modification routines contain two arguments—the 
input attribute block number (iatb) and the output attribute block number (oath). 
Table 9-2 lists the default settings of general attributes. 


Table 9-2 Default Settings of General Attributes 


General 

Default 

Modification 

Attribute 

Setting 

Routine 

Background index^ 

Index 0 

UIS$SET_BACKGROUND_INDEX 

Writing index 

Index 1 

UIS$SET_WRITING -INDEX 

Writing mode 

Overlay 

UIS$SET_WRITING_MODE 

^ Index of the background color in the virtual color map. 

2 Index of the foreground color in the virtual color 

map. 


Perform attribute modification using the following procedure: 

1. Choose an appropriate attribute modification routine to modify the attribute. 

2. Specify 0 as the iatb argument to obtain a copy of attribute block 0. 

3. Specify a number from 1 to 255 as the oatb argument. The attribute block can 
then be referenced in subsequent UIS graphics and text routines or in any other 
attribute modification routine. 

Graphics and text routines as well as UIS$MEASURE_TEXT, UIS$NEW_TEXT_ 
LINE, and UIS$SET_ALIGNED_POSITION reference attribute blocks in the atb 
argument. 


9.3 Structure of Graphic Objects 

There are three types of graphic objects: (1) geometric shapes such as circles, 
ellipses, points, lines, and polygons, (2) text, and (3) raster images. Graphic objects 
consist of a pattern. In memory, the pattern represents one or more bit settings to 0 
or 1 that comprise the actual graphic object. 

When these entities are written in the virtual display, the UIS writing modes interpret 
the bit settings that comprise these objects in different ways. 
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Text 

In the case of text, a standard character within the default font displayed on the 
workstation screen represents the bitmap image of a cell in memory. The size of the 
cell varies and depends on the type of font. UIS draws monospaced and proportionally 
spaced text. Monospaced fonts use a standard cell size for all letters within the font. 
However, the standard cell size varies depending on the monospaced font you are 
using. 

Proportionally spaced fonts use character cells that vary in width according to the 
letter used. The height of the character cell remains constant for all characters within 
the font. 

The character cell contains the pattern. The remaining bits in the cell are set to 0, 

All bits within the character cell are significant to UIS writing modes. 

Geometric Shapes 

In the case of geometric shapes, only the bit settings that actually comprise the 
pattern are significant. Bit settings in the pattern may be 0 or 1. For example, a 
dotted line represents bit settings of 0 and 1 in a pattern. All bit settings both 0 and 
1 within this pattern are significant to UIS writing modes. 

Raster Images 

When you draw a raster image, you set bits in a bitmap to create text characters or 
geometric shapes. For example, UIS$IMAGE and UIS$SET_POINTER_PATTERN 
use bitmaps to map rasters to the display screen. All bits in the bitmap are significant 
to the UIS writing modes. The following table shows the underlying structures from 
which graphic objects are created. 


Graphic Object Structure 

Text Character cell 

Geometric shapes Pattern 

Raster Image Bitmap image of varying size 


For a given graphic object, the current writing mode determines how the bit settings 
in the appropriate structure are displayed. All bit settings of a particular structure are 
significant to UIS writing modes. Figure 9-1 shows graphic objects as structures that 
UIS writing modes recognize: (1) the letter E within a character cell, (2) a square as 
a pattern, and (3) a bitmap containing the letter E, a square, and a vertical dashed 
line of double thickness. 
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Figure 9-1 Structure of Graphic Objects 
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General Attributes 


9.4 UlS Writing Modes 

There are 14 UIS writing modes; transparent, complement, copy, copy negate, 
overlay, overlay negate, erase, erase negate, replace, replace negate, bit set, bit set 
negate, bit clear, and bit clear negate. The writing mode controls how graphics and 
text routines use foreground and background colors to display graphic objects. The 
default writing mode is overlay. 

Table 9-3 lists how each writing mode functions. 


Table 9-3 UIS Writing Modes 


UIS Writing Modes 
Device-Independent 

UIS$C_MODE_ERAS 

UIS$C_MODE _ER ASN 

UIS$C_MODE_OVER 

UIS$C_MODE_OVERN 


UIS$C_MODE_REPL 


Function 


Displays the current background color for each bit position no 
matter what the bit settings are in the character cell, pattern, 
or bitmap image. 

Displays the current writing color for each bit position no 
matter what the bit settings are in the character cell, pattern, 
or bitmap image. 

Displays the current writing color for bits set to 1 in the 
character cell, pattern, or bitmap image. All bits set to 0 have 
no effect on the existing graphic object. This is the default 
writing mode attribute setting. 

Bitwise complements the character cell, pattern, or bitmap 
image that is, bits originally set to 0 are now set to 1 and vice 
versa. 

The bits now set to 1 in the character cell, pattern, or bitmap 
image display the current writing color. The bits that are now 
set to 0 in the character cell have no effect on any existing 
graphic object. 

Displays the current writing color for bits set to 1 in the 
character cell, pattern, or bitmap image. Bits set to 0 in the 
character cell, pattern, or bitmap image display the current 
background color. 
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Table 9-3 (Cent.) UIS Writing Modes 


UIS Writing Modes 

Function 

Device-Independent 

UIS$C_MODE _REPLN 

Bitwise complements the character cell, pattern, or bitmap 
image. The bits now set to 1 in the character cell, pattern, or 
bitmap image now display the current writing color. Bits now 
set to 0 in the character cell, pattern, or bitmap image now 
display the current background color. 

UIS$C_MODE _COMP 

Where the two graphic objects intersect, the bits in the 
character cell, pattern, or bitmap image are exclusive .OR.ed 
with the existing graphic object. 

UIS$C_MODE_TRAN 

Does not alter the display screen. 

Device-Dependent^ 

UIS$C_MODE_BIC 

The bitwise complement of the character cell, pattern, or 
bitmap image is logically .AND.ed with the existing graphic 
object and background. On mapped color systems, where the 
two graphic objects intersect, the bitwise complement of the 
writing index of the character cell, pattern, or bitmap image is 
logically .AND.ed with the pixel values of the existing graphic 
object and background. 

UIS$C_MODE_BICN 

On monochrome systems, the bits in the character cell, 
pattern, or bitmap image are logically .AND.ed with the 
existing graphic object and background. On mapped color 
systems, the writing index of the character cell, pattern, or 
bitmap image is logically .AND.ed with the pixel values of 
the existing graphic object and background. 

UIS$C_MODE_BIS 

The bits in the character cell, pattern, or bitmap image 
are logically .OR.ed with the existing graphic object and 
background. On mapped color systems, the writing index 
of the character cell, pattern, or bitmap image is logically 
.OR.ed with the pixel values of the existing graphic object and 
background. 


^ These UIS writing modes produce device-dependent results. Depending on the specific operation, 
graphic objects drawn using these writing modes may appear differently on VAXstation monochrome and 
color systems. 
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Table 9-3 (Cent.) UIS Writing Modes 


UIS Writing Modes 

Function 

Device-Dependent^ 

UIS$C_MODE_BISN 

On monochrome systems, the bitwise complement of the 
character cell, pattern, or bitmap image is logically .OR.ed 
with the existing graphic object and background. On color 
systems, the bitwise complement of the writing index of the 
character cell, pattern, or bitmap image is logically .OR.ed 
with the pixel values of the existing graphic object and 
background. 

UIS$C_MODE_COPY 

Displays the character cell, pattern, or bitmap image without 
regard to current background and writing color. On a 
VAXstation monochrome system, bits set to 0 are black, 
and bits set to 1 are white. On mapped color systems, the 
writing index of the character cell, pattern, or bitmap is used 
directly as an index. 

UIS$C_MODE _COP YN 

Displays the character cell, pattern, or bitmap image 
without regard to current background and writing color. 

On monochrome systems, bits set to 0 are white and bits 
set to 1 are black. On mapped color systems, the bitwise 
complement of the writing index of the character cell, pattern, 
or bitmap image is used directly as an index. 

^ These UIS writing modes produce device-dependent results. Depending on the specific operation, 
graphic objects drawn using these writing modes may appear differently on VAXstation monochrome and 

color systems. 



/ 

9.4.1 Using General Attributes 

General attributes affect all graphics images displayed on the screen. These attributes 
are background color, writing color (foreground), and writing mode. 

9.4.1.1 Programming Options 

A program can set different background and writing colors for different display 
viewports for application-specific reasons or, simply, for variety. 

Setting the Background Color 

Modifying the background color attribute sets the value of an index into the color 
map. Modifying the background color affects how the current writing mode 
interprets the bits that comprise background color of the graphic object. You can 
set the background color attribute with UlS$SET_BACKGROUND_INDEX. 






General Attributes 9-9 


Setting the Writing Color 

Modifying the writing color attribute sets the value of an index into the color map. 
Writing color affects the color of the graphic object. You can set the writing color 
with UIS$SET_WRITING_INDEX. 

Setting the Writing Mode 

The writing mode controls how background and foreground colors are used to 
draw graphic objects in the virtual display. You can specify the writing mode using 
UIS$SET_WRITING_MODE. 

9.4.1.2 Program Development I 

Programming Objective 

To draw a graphic object in each of the UIS device-independent writing modes using 
the default background and writing color attribute settings. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and associated viewport. 

3. Draw a line using the default overlay writing mode in the virtual display. 

4. Draw a character at same location in each of the UIS writing modes. 

5. Erase graphic objects in the virtual display using UIS$ERASE and delete the 
window using UIS$DELETE_WINDOW. 

6. Repeat steps 3 through 5. 

The font name MY_FONT_5 is a logical name. 

PROGRAM MODE 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0.3.0.3.0, 6 .0,5.0) 
WD_ID=UIS$CREATE_WINDOW(VD.ID,’SYS$W0RKSTATI0N’) 

CALL UIS$PL0T(VD_ID.0,0.5,1.0,2.0,2.5) 

PAUSE 

C Erase the object in the virtual display and delete the window 

C Display window is deleted in order to change viewport title 

CALL UIS$ERASE(VD_ID.0.0.0.0,3.0.3.0) 

CALL UIS$DELETE_WINDOW(WD_ID) 


PAUSE 
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WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’,’OVERLAY’) 

CALL UIS$SET_FONT(VD_ID.0.1.’MY_F0NT_5’) 

CALL UIS$PLOT(VD_ID.0.0.5.1.0.2.0.2.5) 

CALL UIS$TEXT(VD_ID.l.’D’.1.0.2.0) 

PAUSE 

CALL UIS$ERASE(VD_ID.0.0.0.0.3.0.3.0) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’.’OVERLAY NEGATE’) 
CALL UIS$SET_WRITING_MODE(VD_ID.1.2.UIS$C_MODE_OVERN) 

CALL UIS$PL0T(VD_ID.0.0.5.1.0.2.0.2.5) 

CALL UIS$TEXT(VD.ID.2.’D’.1.0.2.0) 

PAUSE 

CALL UIS$ERASE(VD_ID.0.0.0.0.3.0.3.0) 

CALL UIS$DELETE_WINDOW(WDlID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’.’REPLACE’) 

CALL UIS$SET_WRITING_MODE(VD.ID.2.3.UIS$C_MODE_REPL) 

CALL UIS$PLOT(VD_ID.0.0.5.1.0.2.0.2.5) 

CALL UIS$TEXT(VD_ID.3.’D’.1.0.2.0) 

PAUSE 

CALL UIS$ERASE(VD_ID.0.0.0.0.3.0.3.0) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’.’REPLACE NEGATE’) 
CALL UIS$SET_WRITING_MODE(VD_ID.3.4.UIS$C_MODE_REPLN) 

CALL UIS$PL0T(VD_ID.0.0.5.1.0.2.0.2.5) 

CALL UIS$TEXT(VD_ID.4.’D’.1.0.2.0) 

PAUSE 

CALL UIS$ERASE(VD_ID.0.0.0.0.3.0.3.0) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’.’ERASE’) 

CALL UIS$SET_WRITING_MODE(VD_ID.4.5.UIS$C_MODE_ERAS) 

CALL UIS$PLOT(VD_ID.0.0.5,1.0.2.0.2.5) 

CALL UIS$TEXT(VD_ID.5.’D’.1.0.2.0) 


PAUSE 
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CALL UISIERASE(VD_ID.0.0,0.0,3.0,3.0) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’.’ERASE NEGATE’) 
CALL UIS$SET_WRITING_MODE(VD_ID.5.6.UIS$C_MODE_ERASN) 

CALL UIS$PLOT(VD_ID.0.0.5.1.0.2.0.2.5) 

CALL UIS$TEXT(VD_ID.6.’D’,1.0.2.0) 

PAUSE 

CALL UIS$ERASE(VD_ID,0.0.0.0.3.0.3.0) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’.’TRANSPARENT’) 
CALL UIS$SET_WRITING_MODE(VD_ID,6.7.UIS$C_M0DE_TRAN) 

CALL UIS$PL0T(VD_ID,0.0.5,1.0,2.0,2.5) 

CALL UIS$TEXT(VD_ID.7,’D’.1.0,2.0) 

PAUSE 

CALL UIS$ERASE(VD_ID.0.0.0.0.3.0,3.0) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$W0RKSTATI0N’,’COMPLEMENT’) 

CALL UIS$SET_WRITING_MODE(VD_ID,7,8,UIS$C_MODE_COMP) 

CALL UIS$PL0T(VD_ID.0.0.5.1.0,2.0,2.5) 

CALL UIS$TEXT(VD_ID,8.’D’,1.0,2.0) 

PAUSE 

END 

The program MODE sets the writing mode attribute ten times. The letter D is placed 
over the line. Table 9-3 describes the behavior of the UlS writing modes when text 
or geometric shapes such as circles are placed on top of an existing graphic object. 
Remember character cells refer to text, while patterns refer to geometric shapes. 

9.4.1.3 Calling UIS$SET-BACKGROUND_iNDEX, UIS$SET-WRITING_INDEX, 
and UIS$SET-WRITING-MODE 

To illustrate the effects of the writing modes, imagine that the character cell is 
slowly lowered onto the virtual display containing an existing graphic object drawn 
in OVERLAY mode—a line. As it approaches the plane of the virtual display, the 
writing mode of the character cell determines the final appearance of the graphic 
object. See Table 9-3 for a description of each writing mode. 

The default background and writing color are in effect as shown in Figure 9-2. 
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Figure 9-2 UIS Device-Independent Writing Modes 
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Figure 9-2 (Cont.) UIS Device-Independent Writing Modes 



9.4.1.4 Program Development II 

Programming Objective 

To illustrate the behavior of the device-dependent writing modes. 

Programming Tasks 

1. Create an eight-entry virtual color map containing intensity values. 

2. Draw three overlapping circles—one in overlay mode and two in bit set mode. 

3. Redraw the same circles—one in overlay mode, one in bit clear mode, and one 
in bit set mode. 

4. Redraw two of the circles in the remaining device-dependent writing modes. 
One circle is always drawn in OVERLAY mode. Both are drawn using the same 
writing index. 

PROGRAM PLANE.MODES 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY;UISUSRDEF’ 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

REAL*4 I_VECT0R(8) O 

DATA I_VECT0R/0.0.0.125,0.25,0.375,0.50,0.625,0.75,1.0/ O 

DATA VCM_SIZE/8/ © 

DATA INDEX2/2/ O 

DATA INDEX4/4/ © 
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VCM_ID=UIS$CREATE_COLOR_MAP(VCM_SIZE) 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0.40.0,40.0,15.0.15.0,VCM.ID) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’) 

CALL UIS$SET_INTENSITIES(VD_ID.0.8,I.VECTOR) 

CALL UIS$SET_FONT(VD_ID.O.1.’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD_ID.1.1.PATT$C_FOREGROUND) 

CALL UIS$SET_FONT(VD_ID,0.2.’UIS$FILL_PATTERNS’) 

CALL UIS$SET_WRITING_INDEX(VD_ID.2.2.INDEX2) © 

CALL UIS$SET_WRITING_MODE(VD_ID.2.2,UIS$C_MODE_BIS) 

CALL UIS$SET_FILL_PATTERN(VD_ID,2.2.PATT$C_FOREGROUND) 

CALL UIS$SET_WRITING_INDEX(VD_ID,2.4.INDEX4) O 

CALL UIS$CIRCLE(VD_ID,1,15.0,20.0,10.0) © 

CALL UIS$CIRCLE(VD_ID.2,25.0,20.0,10.0) © 

CALL UIS$CIRCLE(VD_ID.4,20.0,30.0,10.0) © 

PAUSE 

CALL UIS$SET_WRITING_M0DE(VD_ID,4.4.UIS$C_M0DE_BIC) © 

CALL UIS$CIRCLE(VD.ID.4,20.0.30.0.10.0) 

PAUSE 

CALL UIS$ERASE(VD_ID) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’) 

CALL UIS$SET_WRITING_MODE(VD_ID.2.2.UIS$C_MODE_BICN) 

CALL UIS$CIRCLE(VD_ID,1,15.0,25.0,10.0) © 

CALL UIS$CIRCLE(VD_ID.2.25.0,25.0,10.0) © 

PAUSE 

CALL UIS$ERASE(VD_ID) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD.ID.’SYS$WORKSTATION’) 

CALL UIS$SET_WRITING_MODE(VD.ID.2.2,UIS$C_MODE_BISN) 

CALL UISSCIRCLE(VD.ID.1,15.0,25.0,10.0) © 

CALL UISSCIRCLE(VD.ID,2,25.0,25.0,10.0) © 

PAUSE 

CALL UIS$ERASE(VD.ID) 

CALL UIS$DELETE.WINDOW(WD.ID) 


PAUSE 
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WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’) 

CALL UIS$SET_WRITING_MODE(VD_ID.2.2.UIS$C_MODE_COPY) 

CALL UIS$CIRCLE(VD_ID,1.15.0.20.0.10.0) © 

CALL UIS$CIRCLE(VD_ID.2.25.0.20.0.10.0) © 

PAUSE 

CALL UIS$ERASE(VD_ID) 

CALL UIS$DELETE_WINDOW(WD_ID) 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’) 

CALL UIS$SET_WRITING_MODE(VD_ID.2.2.UIS$C_M0DE_C0PYN) 

CALL UIS$CIRCLE(VD_ID.1.15.0.20.0.10.0) ® 

CALL UIS$CIRCLE(VD_ID.2.25.0.20.0.10.0) © 

PAUSE 

END 

An array I_VECTOR is declared to hold the intensity values O. Each location in the 
array element is initialized with an intensity value 0. The color map size variable is 
initialized to the number of color map entries ©. Color index variables index! and 
indexi are initialized O ©. 

Three circles are drawn © O © using three different indices in the virtual color 
map—index 1 (the default), index 2, and index 4 © O. The circles are filled with the 
current foreground color. The following table lists the circles, their writing modes 
and indices and corresponding intensity values. 


Circle 

Writing 

Mode 

Writing 

Index 

Intensity 

Value 

1 

Overlay 

1 

0.0 

2 

Bit Set 

2 

0.125 

3 

Bit Set 

4 

0.375 


The three circles are redrawn with circle 3 drawn in Bit Clear mode ©. 

In subsequent drawings, only overlapping circles 1 and 2 are redrawn. Circle one is 
always drawn in overlay mode © © © © © while circle 2 is drawn in the remaining 
writing modes ©©©©©. 
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9.4.1.5 Using Device-Dependent Writing Modes 

The preceding program PLANE—MODES produced Figures 9-3 through 9-8. In 
each of the figures, the circle on the left (circle 1) was drawn in overlay mode and 
writing index 1. The circle on the right (circle 2) was drawn in a different writing 
mode with a writing index 2. The circle on top (circle 3) was drawn with writing 
index 4 and is drawn in Figures 9-3 and 9-4 only. The following table lists the 
writing indices, their binary value and binary bitwise complements. 


Object 

Writing 

Index 

Binary 

Value 

Bitwise 

Complement 

Background 

0 

OOO 2 

OOO 2 

Circle 1 

1 

OOI 2 

IIO 2 

Circle 2 

2 

OIO 2 

IOI 2 

Circle 3 

4 

IOO 2 

OII 2 


In Figure 9-3, whenever the circles 1, 2, and 3 intersect, their writing indices OOI 2 , 
OIO 2 , and IOO 2 / are logically .OR.ed with the pixel values of the existing graphic 
objects and the background. The bit set writing mode has the effect of combining 
the value of the bit plane settings of each object. Therefore, the intersections of the 
circles are lighter than the rest of the circles. 
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Figure 9-3 Bit Set Mode 
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In Figure 9-4, circle 3 is drawn in bit clear mode with a writing index of 4 or IOO 2 . 
Circle 2 is drawn in bit set mode in writing index 2 or OIO 2 . The binary bitwise 
complement of the writing index of circle 3 is IOI 2 . It is logically .AND.ed with the 
pixel values of the existing graphic objects—circle 1, circle 2, and the background. In 
bit clear mode the appropriate bit plane settings are now changed such that, circle 3 
appears to blend into the background and circles 1 and 2. 


Figure 9-4 Bit Clear Mode 
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In Figure 9-5 the binary bitwise complement of the writing index of the circle 2 is 
IOI 2 . It is logically .OR.ed with the pixel values of the existing graphic object and 
background which are 001 2 and OOO 2 . In bit set negate mode the appropriate bit 
plane settings are now changed such that all of circle 2 is drawn in writing index 5. 


Figure 9-5 Bit Set Negate Mode 
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In Figure 9-6, the writing index of the circle 2 OIO 2 is logically .AND.ed with the 
pixel values of the existing circle 001 2 and the background OOO 2 to produce the pixel 
value OOO 2 . The appropriate bit plane settings are now changed such that all of circle 
2 including the area of intersection with circle 1 match the background. 

Figure 9-6 Bit Clear Negate Mode 
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In figure 9-7 the writing index of circle 2 is used as the index in the virtual color 
map to draw the circle regardless of existing graphic objects or background. 

Figure 9-7 Copy Mode 
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In Figure 9-8, the binary bitwise complement of the writing index of circle 2 IOI 2 
was used as the index into the virtual color map to draw the circle regardless of 
existing graphic objects or background. 

Figure 9-8 Copy Negate Mode 
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Chapter 10 
Text Attributes 


10.1 Overview 

UIS draws characters in the virtual display according to the specifications of the 
particular font. The appearance or shape of characters remains unaltered unless an 
appropriate text attribute is changed. Likewise, UIS draws characters and character 
strings at user-specified locations within the coordinate space. This orientation within 
the coordinate space does not change unless an appropriate attribute modification 
routine is executed. 

The orientation and shape of characters and character strings defines spatially how 
UIS draws these objects on the display screen. Text attribute modification routines 
allow you to alter the appearance of characters and character strings and redefine the 
spatial relationship of a character to other characters in significant ways. This chapter 
discusses the following topics: 

• Structure of text 

• Using text attributes 

Refer to Section 10.3.1 for information about how to modify the default text attribute 
settings of attribute block 0. 


10.2 Structure of Text 

The underlying structure of a single character is a character cell. Every character 
drawn on the display screen is contained within a character cell. Figure 10-1 
describes a character cell and its reference points. 
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Figure 10-1 Character Cell 


Top of Character Cell 



10.2.1 Monospaced and Proportionally Spaced Fonts 

For text drawing purposes fonts are either monospaced or proportionally spaced. 
Monospaced fonts use a standard character cell size for each characters within 
the font. The character cells of proportionally spaced fonts vary in width for each 
character within the font, although the height of each cell is the same for each 
character in the font. Figure 10-2 shows the two types of fonts. 

The character cell is a bitmap whose settings are mapped to the display screen as a 
character. 

10.2.2 Lines of Text 

Lines of text share a spatial relationship with other lines of text—for example, a line 
of text within a paragraph. Ordinarily, lines of English text are read from left to 
right. Your eyes trace an imaginary path across the page from the left margin to the 
right margin. By default UIS draws lines of text in this left-to-right direction known 
as the default major path. Normally, when you reach the end of the line, you would 
start reading the next line below this one. When UIS finishes drawing a line of text, 
the secondary downward movement to begin a new line of text drawing is known as 
the default minor path of text drawing. This is the normal relationship between lines 
of English text and the direction in which they are drawn. Figure 10-3 illustrates the 
two default paths that UIS uses to draw text. 
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Figure 10-2 Monospaced and Proportionally Spaced Characters 
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Figure 10-3 Text Path 
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10.2.3 Character Strings 

Characters within character strings also share a spatial relationship with other 
members of the string. 

Text Slope 

UIS draws all characters of a character string at the same angle with the respect to 
the major path. The actual path of text drawing is a line containing the baseline 
points of all the character cells in a character string. The angle between the actual 
path and the major path, measured counterclockwise is called the angle of text slope. 
UIS can draw text at any angle from 0 to 360 degrees. Figure 10-4 describes how 
text slope can be manipulated. 



Figure 10-4 Text 
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Text Margins 

Character strings are drawn along the actual path of text drawing within certain 
explicit or implicit boundaries called margins. The implied text margin for all 
text output is the minor text path when the angle of text slope is 0 degrees. The 
programming interface lets you set explicit text margins that are always parallel to 
the implied margins. 

Character Spacing 

Spacing between characters and lines can be increased uniformly throughout the 
character string through the use of x and y spacing factors. The size of the characters 
remains constant space between them diminishes or increases. 

Figure 10-5 shows how text path affects character spacing. 
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Figure 10-5 Character Spacing 
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Figure 10-5 (Cont.) Character Spacing 
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Text Formatting 

Character strings can be arranged on a line in many ways through justification. 
Formatted character strings are drawn as follows: (1) flush against the left margin, 

(2) flush against the right margin, (3) centered between the margins, and (4) both 
right and left justified or fully justified. 

10.2.4 Character Cell 

The components of a character cell share a spatial relationship with each other. 

The orientation and shape of a single character cell in the virtual display can be 
altered through character rotation, slanting, and scaling. These attributes when 
modified alter the character cell with respect to its baseline vector. For example a 
scaled character may have its height modified changing the height-relationship. The 
resulting letter may appear "squat" or vertically elongated. 

Rotating Characters 

An individual character is rotated about its baseline point. The angle of character 
rotation is the angle between the baseline vector and the actual path of text drawing 
measured counterclockwise. Figure 10-6 describes simple character cell rotation 
about the baseline point. 



10-10 Text Attributes 



00000000 

00000000 

00000000 

00000000 

00000000 

00000000 

00000000 

00000000 

00000000 



Baseline Vector 
and 

Actual Path 


o 

o 



Baseline Vector 



^ /? = Positive Character Rotation 


ZK 5277 86 



Text Attributes 10-11 


Figure 10-7 describes character rotation and text slope manipulation performed 
simultaneously. 

Figure 10-7 Character Rotation with Slope Manipulation 
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Figure 10-7 (Cont.) Character Rotation with Slope Manipulation 
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When the character rotation attribute is set to 0 and text slope is 0 degrees, the angle 
of character rotation behaves in the following manner: 


Slope 

(degrees) 

Major 

Path 

Rotation 

(degrees) 

0 

Left to right (default) 

0 

0 

Bottom to top 

-90 

0 

Right to left 

-180 

0 

Top to bottom 

-270 


Figure 10-8 describes the appearance of the angle of rotation after text path 
modification when default character rotation is in effect. 
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Figure 10-8 
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Figure 10-8 (Cont.) Text Path Manipulation Without Character Rotation 


00000000 00000000 
00000000 00000000 
00000000 00000000 
00000000 00000000 
00000000 00000000 


00000000 00000000 



Actual Path - Major Path 


LEFT 


RIGHT 



ZK-5358^ 


(Continued on next page) 


























Text Attributes 10-17 


Slanting Characters 

Character slant is a measure of the angle between the up vector of the character cell 
and baseline vector. Character slant is 0.0 when this angle is 90 degrees. As slant 
increases, the up vector rotates clockwise toward the baseline vector, until at a slant 
of 90 degrees, the two vectors coincide. Figure 10-9 show a slanted character cell 
where the actual path and the default major path form an angle of 0 degrees. 
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Figure 10-10 shows character slanting, character rotation, and text slope operations 
performed simultaneously on two character cells. 

Figure 10-10 Character Slanting and Rotation with Slope Manipulation 



(Continued on next page) 


10-20 Text Attributes 


Figure 10-10 (Cont.) Character Slanting and Rotation with Slope Manipulation 
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Scaling Characters 

Character scaling involves increasing or diminishing the size of the character cell. 
Scaling factors specify the world coordinate space in which the scaled character is 
drawn. The character cell is expanded or contracted to fill the specified space. 
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Figure 10-11 Character Scaling 
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10.3 Using Text Attributes 

As you can see, there are several attributes associated with text output. You are not 
limited to simply choosing from a library of fonts. For example, you can modify the 
appearance of any font through scaling and slanting and also alter the way in which 
the system draws the text in the virtual display using formatting modes and paths. 

The following routines are not attribute modification routines but included here to 
illustrates other types of text manipulation. 


Routine 

Function 

UIS$NEW_TEXT_LINE 

Moves the current text position along the minor text 
path 

UIS$SET_ALIGNED_POSITION 

Sets the current text position at the upper-left corner 
of the character cell 

UIS$SET_POSITION 

Sets the current text position at the baseline point of 
the character cell 


These routines contain an atb argument which indicates that appropriate text 
attribute settings can modify their behavior. 
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10.3.1 Modifying Text Attributes 

When you modify text attributes, you do not change the default attribute settings 
within attribute block 0 itself. You should think of attribute block 0 as a template 
of default settings and you are modifying a copy of this attribute block for use 
within your program. Attribute modification routines contain two arguments—the 
input attribute block number (iatb) and the output attribute block number (oatb). 
Table 10-1 lists all text attributes and their default settings. 


Table 10-1 Default Settings of Text Attributes in Attribute Block 0 


Text 

Default 

Modification 

Attribute 

Setting 

Routine 

Character rotation 

0.0 

UIS$SET_CHAR_ROTATION 

Character size 

Specified by the font 

UIS$SET_CHAR_SIZE 

Character slant 

0.0 

UIS$SET_CHAR_SLANT 

Character spacing 

0.0,0.0 

UIS$SET_CHAR_SPACING 

Text formatting 

Normal 

UIS$SET_TEXT_FORMATTING 

Text margins 

0.0,0.0 

UIS$SET_TEXT_MARGINS 

Text path 

Left to right (default 
major path) 
top to bottom (default 
minor path) 

UIS$SET_TEXT_PATH 

Text slope 

0.0 

UIS$SET_TEXT_SLOPE 

Font 

Multinational ASCII, 
14-point, fixed pitch 

UIS$SET_FONT 


Perform attribute modification using the following procedure: 

1. Choose an appropriate attribute routine to modify the attribute. 

2. Specify 0 as the iatb argument to obtain a copy of attribute block 0. 

3. Specify a number from 1 to 255 as the oatb argument. The attribute block can 
then be referenced in subsequent UIS graphics and text routines or in any other 
attribute modification routine. 

Graphics and text routines as well as UIS$MEASURE_TEXT, UIS$NEW_TEXT_ 
LINE, and UIS$SET_ALIGNED_POSITION reference modified attribute blocks in 
the atb argument. These routines are discussed later in this chapter. 
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10.4 Programming Options 

You can modify text attributes within your application to change the font type, 
margin settings, and character spacing. 

Fonts 

You can change the font type of a line of text using UIS$SET_FONT. You must 
specify the desired font file name in the font_id argument. Font files reside in the 
directory SYS$FONT. The directory contains one file of fill patterns (UIS$FILL_ 
PATTERNS) and 26 font files. You can choose between two types of fonts. 

• Multinational character fonts — Contain international alphanumeric characters, 
including characters with diacritical marks. 

• Technical fonts — Include scientific and mathematical symbols. 

Font File Names 

A standard 31-character file name identifies each font file as follows: 
DTERMINM060K00PG0001UZZZZ02A000 

The first 16 bytes of this sample file name (representing unique font specifications) 
are explained in the following table. 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type family ID 

TERMIN 

Terminal 

8 

Spacing 

M36 

13 pitch (monospaced) 

9-11 

Type size 

O 6 O 36 

24 points (240 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


Refer to Appendix C for more information about UIS fonts. 

NOTE: You can define logical names to represent font file names. 
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Font File Types 

The following table lists sample font file names and their device-dependent font file 
types. 


System 

Font File Name 

Mutinational Character Set Fonts 

Monochrome 

Intensity or color 

DTERMINM06OK00PG0001UZZZZ02A000.VWS$FONT 

DTERMINM06OK00PG0001UZZZZ02A000.VWS$VAFONT 

Technical Character Set Fonts 

Monochrome 

Intensity or color 

DVWSVT0G03CK00GG0001QZZZZ02A000.VWS$FONT 
DVWSVT0G03CK00GG0001QZZZZ02 AOOO. VWS$VAFONT 


NOTE; Whenever you reference a font file name as in UIS$SET_FONT, you should 
not specify the directory SYS$FONT or the file type. 

Setting the Text Margins 

You can set the left and right margins with UIS$SET_TEXT_MARGINS. 

Setting the Text Formatting Mode 

There are four text formatting modes—left justification, right justification, center 
justification, and full justification. The text formatting modes are set using 
UIS$SET_TEXT_FORMATTING. 

NOTE: UIS$SET_TEXT-_FORMATTING does not automatically wrap long lines of 
text. 

Setting the Character Spacing 

You can alter the spacing between character, or kerning, or the spacing between lines, 
also known as leading, with UIS$SET_CHAR_SPAGING. 

New Text Lines 

When you are writing text and you need to move to a new line, use 
UIS$NEW_TEXT_LINE. When you create a new line of text, the current position 
becomes the beginning of the new line. When used in conjunction with 
UIS$SET_CHAR_SPAGING, you can manipulate the spacing between lines, or 
leading. 

Character Rotation 

You can rotate characters about a pivotal point called the baseline point from 0 to 
360 degrees using UIS$SET_GHAR_ROTATION. 
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Aligning Text Along the Baseline and Top of Chararcter Cell 

You can align text along the baseline vector using UIS$SET_POSlTION or along the 
upper-left comer of the character cell using UIS$SET_AL1GNED_P0SIT10N. 

Specifying Character Slant 

You can specify the angle relative to the text baseline vector by which text is to be 
slanted using UIS$SET_CHAR_SLANT. 

Specifying Character Scaling 

You can specify the width and height for characters in a font using 
UIS$SET_CHAR_SIZE. 

Specifying Slope of the Text Baseline 

You can specify the angle of the actual path of text drawing relative to the major 
path using UIS$SET_TEXT_SLOPE. 

Specifying the Text Path 

You can specify the direction of text drawing with U1S$SET_TEXT_PATH. There are 
four directions in which text can be drawn: (1) left to right, (2) right to left, (3) 
bottom to top, and (4) top to bottom. You must use these direction in the context 
of a major text drawing path and a minor text drawing path. The major path of 
text drawing is the relationship between letters; the minor path is the relationship 
between lines. 

10.4.1 Program Development I 

Programming Objective 

To draw the multinational character set fonts available in the directory SYS$FONT 
and to show how to move to a new text line. 

Programming Task 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Modify the font attribute in attribute block 0. 

4. Move to the beginning of a new line using UIS$NEW_TEXT_L1NE and the 
appropriate attribute setting. 

5. Draw a line of text. 

6. Repeat steps 3 through 5. 



10-26 Text Attributes 


Note that font file names used in the program TEXT_1 are logical names. Some 
examples of a font occupy two lines. 

PROGRAM TEXT.l 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,30.0,30.0.20.0,10.0) 
WD_ID1=UIS$CREATE_WIND0W(VD_ID.’SYS$W0RKSTATI0N’,’FONTS’) 

CALL UIS$SET_F0NT(VD_ID.0.1.’MY_F0NT_1’) O 

CALL UIS$TEXT(VD_ID,1,’The quality of mercy is not strained’, 

2 1.0,30.0) @ 

CALL UIS$SET_F0NT(VD_ID.0.2,’MY_F0NT_2’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.2) ® 

CALL UIS$TEXT(VD_ID,2,’Long visits bring short compliments’) 

CALL UIS$SET_F0NT(VD_ID,0,3,’MY_F0NT_3’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.3) 

CALL UIS$TEXT(VD_ID,3.’Wise men make proverbs and fools’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.3) 

CALL UIS$TEXT(VD_ID.3.’repeat them’) 

CALL UIS$SET_F0NT(VD_ID.0,4,’MY_F0NT_4’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.4) 

CALL UIS$TEXT(VD_ID.4.’Je pense done je suis’) 

CALL UIS$SET_F0NT(VD_ID.0.5,’MY_F0NT_5’) 

CALL UIS$NEW_TEXT_LINE(VD_ID,5) 

CALL UIS$TEXT(VD_ID.5.’Do well and have well’) 

CALL UIS$SET_F0NT(VD_ID.0.6.’MY_F0NT_6’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.6) 

CALL UIS$TEXT(VD_ID,6,’You cannot make a crab walk straight’) 

CALL UIS$SET_F0NT(VD_ID.0.7,’MY_F0NT_7’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.7) 

CALL UIS$TEXT(VD_ID.7.’Great minds think alike’) 

CALL UIS$SET_FONT(VD_ID.0.8.’MY_F0NT_8’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.8) 

CALL UIS$TEXT(VD_ID,8,’One today is worth two tomorrows’) 

CALL UIS$SET_FONT(VD_ID,0.9.’MY_F0NT_9’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.9) 

CALL UIS$TEXT(VD_ID,9,’With Latin, a horse, and money, you may’) 
CALL UIS$NEW_TEXT_LINE(VD_ID.9) 

CALL UIS$TEXT(VD_ID,9.’travel the world’) 
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CALL UIS$SET_F0NT(VD_ID.0.10.’MY_F0NT_10’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.10) 

CALL UIS$TEXT(VD_ID.10.’Whispered words are heard afar’) 

CALL UIS$SET_FONT(VD_ID.0.1!.’MY_F0NT_11’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.ll) 

CALL UIS$TEXT(VD_ID.ll.’Et tu. Brute?’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.ll) 

CALL UIS$TEXT(VD_ID.ll.’Per ardua astra’) 

CALL UIS$SET_FONT(VD_ID.0.12.’MY_F0NT_12’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.12) 

CALL UIS$TEXT(VD_ID.12.’Velut arbor aevo’) 

CALL UIS$SET_FONT(VD_ID.0.13.’MY_F0NT_13’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.13) 

CALL UIS$TEXT(VD_ID.13.’One mule scrubs another’) 

CALL UIS$SET_FONT(VD_ID.0.14,’MY_F0NT_14’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.14) 

CALL UIS$TEXT(VD_ID.14.’Life is just a bowl of cherries’) 

PAUSE 

END 

The font attribute in attribute block 0 is modified in fourteen calls to UIS$SET_PONT 
O. There now exists an attribute block containing a modified font attribute for each 
font in SYS$FONT. These attribute blocks are identified by their output attribute 
block number when they were created. 

The atb argument of UIS$TEXT © uses the appropriate attribute block number to 
generate text in the desired font. 

A call to U1S$NEW_TEXT_LINE O causes each new line of text to begin on a new 
line at the left margin. 


10.4.2 Calling UIS$SET_FONT and UIS$NEW-TEXT_LINE 

Once again, note the positional order of the attribute routines. Attribute routines 
modify the attribute block used by the routine creating the graphic object and, 
therefore, must precede that routine. The attribute routine and the output routine 
must reference the same attribute block. Figure 10-12 contains examples of each of 
the UIS fonts. 
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Figure 10-12 UIS Fonts 
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Refer to Appendix C for a listing of UIS fonts. 
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10.4.3 Program Development II 

Programming Objective 

To increase character and line spacing in two lines of text. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with a title. 

3. Draw a line of text using the default character spacing factor. 

4. Modify the character and line spacing factors using UIS$SET_CHAR_SPACING. 

5. Draw a line of text using the modified spacing attribute. 

6. Move to the beginning of a new line using UIS$NEW_TEXT_LINE with the 
modified spacing attribute. 

7. Repeat steps 3 through 5. 

PROGRAM SPACE.l 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0,0.0.40.0.40.0,18.0.6.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’,’KERNING AND LEADING’) 

CALL UIS$SET_FONT(VD_ID.0.15,’MY_F0NT_1’) O 

CALL UIS$TEXT(VD_ID.15,’The best mirror is an old friend’.0.0.40.0) O 

CALL UIS$NEW_TEXT_LINE(VD_ID,15) 0 

CALL UIS$SET_CHAR_SPACING(VD_ID.15.16,3.0.3.0) O 

CALL UIS$TEXT(VD_ID,16,’The best mirror is an old friend’) @ 

CALL UIS$NEW_TEXT_LINE(VD_ID.16) © 

CALL UIS$TEXT(VD_ID,15,’In the coldest flint there is hot fire’) 

CALL UIS$NEW_TEXT_LINE(VD.ID.15) 

CALL UIS$TEXT(VD_ID,16,’In the coldest flint there is hot fire’) 

PAUSE 

END 

A call to UIS$SET_FONT O sets the font attribute. The attribute block containing 
the newly modified font attribute is assigned the number 15. The logical name 
MY_FONT_l denotes a font that is used throughout the program. 

The first line of text is drawn in the appropriate font 0. The text is drawn at the 
location in the virtual display specified in UIS$TEXT. 
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When the next line of text is written, UIS$NEW_TEXT_LINE references attribute 
block number 15 ®. U1S$NEW_TEXT_LINE uses the characteristics of the new 
font to determine proper line spacing. If you had used attribute block number 0, 
UIS$NEW_TEXT_LINE would use the characteristics of the default font. In that 
case, the descenders of letters in the previous line and the ascenders of the letters of 
the new line might crash into each other or obscure portions of letters in either line. 
Therefore, you should call UIS$NEW_TEXT_LINE using the appropriate attribute 
block number. 

Attribute block 15 is further modified in a call to UIS$SET_CHAR_SPAGING ©. 
Attribute block 15 containing the previously modified font attribute and now the 
newly modified character spacing attribute is assigned the number 16. 

NOTE: Attribute block 15 still exists and can be referenced. 

The character and line spacing attributes are set to a factor of 3. Characters are 
placed apart by a factor of 3 times their width. Lines of text are placed apart by a 
kctor of 3 times the height of the character. 

Text is drawn and spaced, character by character, according to the values specified 
in font attribute and the character spacing attribute in attribute block 16 0. The 
character spacing component of the character spacing attribute, or x factor determines 
spacing between characters for left-to-right and right-to-left text paths. 

A call to UIS$NEW_TEXT_LINE 0 creates a new text line using attribute block 
number 16. UIS$NEW_TEXT_LINE uses the line spacing component of the character 
spacing attribute, or y factor to determine spacing between lines. The y factor is used 
for top-to-bottom and bottom-to-top text paths. 

10.4.4 Calling UIS$SET-CHAR-SPACING 

You can call character spacing in one line of the previous example by calling 
UIS$SET_CHAR_SPAGING as shown here. 

UIS$SET_GHAR_SPAGING specified a spacing factor of 3. If you ran this program 
with the changes described above, your workstation screen would display the graphic 
objects shown in Figure 10-13. 
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Figure 10-13 Character and Line Spacing 
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7. Repeat step 4 using UIS$SET_POSITION. 

8. Repeat steps 5 and 6. 

PROGRAM SET.POS 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0,40.0.40.0,18.0.5.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’,’TEXT ALIGNMENT’) 

CALL UIS$PLOT(VD_ID.0.0.0,35.0,40.0,35.0) O 

CALL UIS$SET_FONT(VD_ID.0.1.’MY_F0NT_7’) 

CALL UIS$SET_ALIGNED_POSITION(VD.ID.1,0.0,35.0) Q 

CALL UIS$TEXT(VD_ID.l.’Never refuse a good offer’) © 

CALL UIS$PLOT(VD_ID.0.0.0,20.0,40.0,20.0) O 

CALL UIS$SET_POSITION(VD_ID,0.0,20.0) © 

CALL UIS$SET_F0NT(VD_ID.0.2,’MY_F0NT_5’) 

CALL UIS$TEXT(VD_ID.2.’Weigh justly and sell dearly’) © 

PAUSE 

END 

Two horizontal and parallel lines are drawn with UIS$PLOT O O. 

Both calls to UIS$SET_ALIGNED_POSITION and UIS$SET_POSITION © © use 
the starting points of the respective lines to establish the current position for new text 
output unless the current position is specified in UIS$TEXT. 

Text creation © © begins by default at the current position established in 
UIS$SET_ALIGNED_POSITION and UIS$SET_POSITION. 

10.4.6 Calling UIS$SET_POSITION and 
UIS$SET_ALIGNED_POSITION 

The first sentence shown in Figure 10-14 illustrates the alignment of text along the 
top of the character cell. The second sentence is aligned on the baseline vector. 



Text Attributes 10-33 


Figure 10-14 Baseline and Top of Character Cell 
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10.4.7 Program Development IV 

Programming Objective 

To draw characters at three different angles relative to the baseline vector. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and a viewport with a title. 

3. Choose a font and modify the font attribute in attribute block 0. 

4. Draw a character string at the default angle 0 degrees. 

5. Modify the character slant attribute using UIS$SET_CHAR_SLANT. 

6. Draw the character string again using the modified attribute block. 

7. Repeat step 5 specify negative degrees. 

The file name MY_FONT_12 is a logical name for a font in SYS$FONT. 

PROGRAM SLANT 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0,0.0,20.0.5.0.18.0,4.5) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’.’CHARACTER SLANTING’) 

CALL UIS$SET_F0NT(VD_ID.0,1.’MY_F0NT_12’) O 

CALL UIS$TEXT(VD_ID.l,’Unslanted characters do not lean’.0.1.5.0) O 
















10-34 


Text Attributes 


PAUSE 

CALL UIS$SET_CHAR_SLANT(VD_ID.1.2.25.0) O 

CALL UIS$TEXT(VD_ID,2.’Slanted characters lean forward’,0.5.3.0) 

PAUSE 

CALL U1S$SET_CHAR_SLANT(VD_1D.1.3,-25.0) O 

CALL U1S$TEXT(VD_1D,3,’Slanted characters lean backward’,0.5,1.0) 

PAUSE 

END 

A font is selected using UIS$SET_FONT O. A text string is drawn using the default 
attribute setting in attribute block 0 ©. 

Next, the character slant attribute is modified ® to specify a 25 degree shift to the 
right of a line perpendicular to the text baseline. 

The character slant attribute is further modified O to specify a 25 degree shift to the 
left of a line perpendicular to the text baseline. 

10.4.8 Calling UIS$SET_CHAR-SLANT 

First, the character string is drawn at the default slant—0 degrees. Next, the 
character string is drawn twice slanting each character 25 degrees to the right of 
a line perpendicular to the text baseline and then 25 degrees to the left of that line. 

Figure 10-15 Character Slanting 
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10.4.9 Program Development V 

Programming Objective 

To draw a character string whose actual path increases at 20-degree increments from 
0 to 340 degrees. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Create DO loop that increases from 0 to 360 degrees by 20-degree increments. 

• Place the slope attribute modification routine UIS$SET_TEXT_SLOPE within 
the DO loop. 

• Place the text drawing routine UIS$TEXT within the DO loop. 

The font file name MY_FONT_13 is a logical name for a font in SYS$FONT. 

PROGRAM SLOPE 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYSSLIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0,0.0.50.0,50.0.10.0.10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’,’text slope’) 

CALL UIS$SET_F0NT(VD_ID,0.1.’MY_F0NT_13’) O 

DO 1=0.340,20 @ 

CALL UIS$SET_TEXT_SL0PE(VD_ID.1.2.FL0AT(I)) @ 

CALL UIS$TEXT(VD_ID.2.’ Slope!’,25.0.25.0) O 

ENDDO 0 

PAUSE 

END 

A font is selected and the default font attribute setting is modified using UIS$ SET- 
FONT O. 

A DO loop is established 0 0. The counter I is initialized to 0 and will increase by 
increments of 20. The angle argument in UIS$SET_TEXT_SLOPE uses the value of 
I as the new text baseline attribute setting 0. The VAX FORTRAN function FLOAT 
changes the integer counter 7 to a real number 0 . 

Using UIS$TEXT, text strings are drawn from a central point (25.0,25.0) at 20-degree 
intervals O. 
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10.4.10 Calling UIS$SET_TEXT_SLOPE 

Text strings are drawn at 20-degree intervals from 0 degrees to 360 degrees. The 
angle of each new text baseline increases by a multiple of 20. Text is drawn in a 
counterclockwise direction from the default horizontal baseline. 

Figure 10-16 Manipulating the Text Baseline 
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10.4.11 Program Development VI 

Programming Objective 

To rotate each character in order to offset text slope. 








Text Attributes 


10-37 


Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Create a DO loop. 

4. Modify the attributes within the DO loop. 

PROGRAM SLOPE.ROTATE 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0,0.0.50.0.51.0.10.0,10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’. 

2 ’TEXT SLOPE AND CHARACTER ROTATION’) 

CALL UIS$SET_FONT(VD_ID.0.1.’MY_F0NT_13’) 

DO 1=0.340.20 

CALL UIS$SET_TEXT_SL0PE(VD_ID,1.2.FL0AT(I)) O 
CALL UIS$SET_CHAR_R0TATI0N(VD_ID.2.2.FL0AT(-I)) 0 
CALL UIS$TEXT(VD_ID.2.’ Rotate!’,24.0.28.5) 

ENDDO 

PAUSE 

END 

This program is identical to the previous program SLOPE except that in addition to 
the text slope attribute we have modified the character rotation attribute. 

Within the DO loop, both attribute modification calls use the value of the counter I 
to increase the angles of text slope and character rotation for different purposes O 0. 

For every 20-degree increase in the angle of text slope, the angle of character 
rotation of each character must be decremented by -20 degrees. Consequently, 
each character's baseline vector remains parallel with the default major path. 


10.4.12 Calling UIS$SET_CHAR_ROTATION 

The program SLOPE—ROTATE draws a series of character strings from a center point 
from 0 to 360 degrees at 20-degree intervals. Because the angle of character rotation 
offsets exactly the angle of text slope, character maintain a readable orientation. 
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Figure 10-17 Character Rotation Without Slanting 


text slope and character rotation 
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If you add a singe call to modify the character slanting attribute, your viewport will 
display character rotation and slanting as the text slope from 0 to 360 degrees at 
20-degree intervals as shown in Figure 10-18. 
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Figure 10-18 Character Rotation with Slanting 
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10.4.13 Program Development VII 

Programming Objective 

To manipulate the width and height of character through scaling. 




















10-40 Text Attributes 


Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with title. 

3. Draw a character string. 

4. Increase the character size for width and height by 1. 

5. Repeat steps 3 and 4. 

Font names used in this program are logical names. 

PROGRAM CHARSIZE 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL*4 WIDTH,HEIGHT 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0,70.0.90.0.12.0.16.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$W0RKSTATI0N’,’CHARACTER SCALING’) 

CALL UIS$SET_F0NT(VD.ID,0,1,’MY_F0NT_1’) O 

CALL UIS$TEXT(VD.ID.1.’Great scott!’.0.0,90.0) © 

CALL UIS$SET_CHAR_SIZE(VD.ID.1.2,.2.0,2.0) © 

CALL UISSTEXT(VD.ID.2.’Great scott!’.0.0.80.0) O 

CALL UISSSET.CHAR.SIZE(VD.ID.1,2,.3.0,3.0) 

CALL UIS$TEXT(VD.ID.2.’Great scott!’,0.0.70.0) 

CALL UISSSET.CHAR.SIZE(VD.ID,1,2,.4.0,4.0) 

CALL UISSTEXT(VD.ID.2.’Great scott!’,0.0,60.0) 

CALL UISSSET.CHAR.SIZE(VD.ID,1,2,,5.0,5.0) 

CALL UISSTEXT(VD.ID.2.’Great scott!’.0.0,50.0) 

CALL UISSSET.CHAR.SIZE(VD.ID,1,2,.6.0,6.0) 

CALL UISSTEXT(VD.ID.2,’Great scott!’.0.0.40.0) 

CALL UISSSET.CHAR.SIZE(VD.ID,1.2,,7.0,7.0) 

CALL UISSTEXT(VD.ID.2,’Great scott!’.0.0,30.0) 

CALL UISSSET.CHAR.SIZE(VD.ID,1,2,.8.0,8.0) 

CALL UISSTEXT(VD.ID.2,’Great scott!’,0.0.20.0) 

CALL UISSSET.CHAR.SIZE(VD.ID,1,2,,9.0,9.0) 

CALL UISSTEXT(VD.ID,2,’Great scott!’,0.0.10.0) 

PAUSE 

END 

A font is selected O. 

The unsealed character string Great scott! is drawn in the virtual display ©. 

The character string is redrawn as scaled text. The scale factors for the width and 
height are incremented ® each time the character string is drawn O. 
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10.4.14 Calling UIS$SET_CHAR_SIZE 

Figure 10-19 shows the character string increasing in height and width as the scale 
factors are incremented. 

Figure 10-19 Manipulating Character Size 
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Chapter 11 

Graphics and Windowing Attributes 


11.1 Overview 

This chapter discusses the following topics: 

• Creating dashed lines 

• Creating lines of varying widths 

• Using fill patterns 

• Using clipping rectangles 


11.2 Using Graphics Attributes 

Graphics attributes affect arc type, line width, line style, and the use of fill patterns. 


11.2.1 Modifying Graphics and Windowing Attributes 

When you modify graphics and windowing attributes, you do not change the default 
attribute settings within attribute block 0 itself. You should think of attribute block 
0 as a template of default settings and you are modifying a copy of this attribute 
block for use within your program. Attribute modification routines contain two 
arguments—the input attribute block number (iatb) and the output attribute block 
number (oatb). Table 11-1 lists the default settings of graphics and windowing 
attributes. 
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Table 11-1 Default Settings of Graphics and Windowing Attributes 


Attribute 

Default 

Setting 

Modification 

Routine 

Arc type 

Open 

UIS$SET_ARC_TYPE 

Fill pattern 

Off 

UIS$SET_FILL -PATTERN 

Line style 

Solid 

UIS$SET_LINE -STYLE 

Line width 

1.0 (unsealed) 

UIS$SET_LINE -WIDTH 

Clipping rectangle 

Off 

UIS$SET_CLIP 


Perform attribute modification using the following procedure: 

1. Choose an appropriate attribute routine to modify the attribute. 

2. Specify 0 as the iatb argument to obtain a copy of attribute block 0. 

3. Specify a number from 1 to 255 as the oatb argument. The attribute block can 
then be referenced in subsequent UIS graphics and text routines or in any other 
attribute modification routine. 

Graphics and text routines reference modified attribute blocks in the atb argument as 
well as UIS$MEASURE_TEXT, UIS$NEW_TEXT_LINE, and 
UIS$SET_ALIGNED_POSITION. 

11.2.2 Programming Options 

Depending on the graphic object to be created—a line, a polygon, an ellipse, or 
circle—there are several attributes to choose from. 

Fill Patterns 

Fill patterns are used to add shading to geometric figures displayed on the 
workstation screen. Fill patterns are most often used to accentuate portions of a 
pie graph. Fill patterns range in coloration from light to heavy. Typically, light fill 
patterns connote light activity or minimal density in graphs. Heavy fill patterns 
connote the opposite meaning—heavy activity or maximum density. 

You can also create your own fill pattern by selecting a character from any UIS font 
to serve as a fill pattern glyph. 

All fill patterns are stored together in a font file in the directory SYS$FONT. For your 
convenience, this file name has been converted to a logical name 
UIS$FILL -PATTERNS. 
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Select a fill pattern in the following manner: 

1. Using UIS$SET_FONT, specify 0 to select a copy of attribute block 0 to modify 
or specify the number of a previously modified attribute block as the input 
attribute block. 

2. Assign an output attribute block number to this newly modified attribute block 
in UIS$SET_FONT. This attribute block number allows you to keep track of 
attributes. You can also modify some other element in this attribute block later 
on, 

3. Specify the name of the fill pattern file in UlS$SET_FONT. Use the predefined 
logical name for the fill pattern file is UIS$FILL—PATTERNS. 

If you wish to use a character from a font other than the default fill pattern file 
as fill pattern glyph, specify the appropriate font name. 

4. Using UIS$SET_FILL—PATTERN, specify the actual fill pattern using a UIS 
symbol in the argument index. A UIS symbol in the form PATT$C_xxxx exists 
for each fill pattern and serves an index of each fill pattern in the file. The 
symbolic constant represents a hexadecimal offset indicating the fill pattern's 
position in the font file. 

If you are creating a fill pattern from a UIS font other than the default fill pattern 
file, specify the ASCII code of the desired character in the index of UIS$SET_ 
FILL-PATTERN. 

NOTE: To disable fill patterns without modifying the fill pattern attribute, do not 

specify the index argument in UIS$SET—FILL—PATTERN. 

Refer to Section 6.4 for more information about UIS constants. 

Setting the Arc Type 

Perhaps you want to draw a pie chart. You can draw chords or request that no chord 

be drawn using UIS$SET—ARC—TYPE and by specifying one of the constants shown 

in the following table. 


Arc Type Description 

UIS$C_ARC_OPEN Does not draw any chords 

UIS$C_ARC—PIE Draws a line from both end points of the arc to the center position 

UIS$C_ARC_CHORD Draws a line connecting the end points of the arc 


Remember that fill patterns are not drawn in the arc when the arc type attribute is 
specified as OPEN. 
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Line Width 

You can increase the apparent thickness of lines displayed on the workstation screen 
with UIS$SET_LINE—WIDTH. Note that this routine affects the thickness of lines 
created with UIS$LINE, UIS$LINE-ARRAY, UIS$PLOT, UIS$PLOT-ARRAY, and 
UIS$ELL1PSE only. 

Line Style 

Occasionally, a solid line is not exactly what you need. You can create dots, hyphens, 
and dashes with UIS$SET—LINE—STYLE. 

11.2.2.1 Program Development I 

Programming Objective 

To draw the different arc types and to demonstrate their use with fill patterns. 
Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with title. 

3. Modify the arc type attribute using the chord arc type in the attribute block 0. 

4. Draw an arc using UIS$CIRCLE with the modified attribute block. 

5. Repeat steps 3 and 4. 

6. Erase the virtual display and delete the display window. 

7. Create a display window and viewport with an identifying title. 

8. Modify the arc type attribute. Select the pie arc type. 

9. Select a fill pattern. 

• Modify the font attribute in attribute block 0. 

• Modify the fill pattern attribute block 0. 

10. Draw an arc using the modified arc type, font, and fill pattern attribute blocks. 

PROGRAM ARC 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0,0.0,40.0,40.0.15.0,15.0) 
WD_ID=UIS$CREATE_WIND0W(VD_ID.’SYS$W0RKSTATI0N’.’CHORD AND PIE’) 

CALL UIS$SET_ARC_TYPE(VD_ID,0.6,UIS$C_ARC_CH0RD) O 
CALL UIS$CIRCLE(VD_ID.6.5.0,20.0,15.0.0.0,150.0) 
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CALL UIS$SET_ARC_TYPE(VD_ID.0.1.UIS$C_ARC_PIE) O 
CALL UIS$CIRCLE(VD_ID.1.23.0.20.0.15.0.0.0.150.0) 

PAUSE 

CALL UIS$DELETE_WINDOW(WD_ID) O 
CALL UIS$ERASE(VD_ID) O 

PAUSE 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYSSWORKSTATION’.’FILLED PIE’) ® 

CALL UIS$SET_ARC_TYPE(VD_ID.O.1.UIS$C_ARC_PIE) 

CALL UIS$SET_FONT(VD_ID.1.2.’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD_ID.2.3.PATT$C_H0RIZ2_6) © 

CALL UIS$CIRCLE(VD_ID.3.18.0.20.0.15.0.0.0.150.0) 

PAUSE 

END 

The program ARC creates two arcs and specifies two ways of closing those arcs O ©. 

In order to change the window caption, we delete the display window and its 
associated viewport ©. Because the second part of the program draws a new graphic 
object, we need to erase existing graphic objects O. 

A new display window is created and its viewport bears a new title. ®. 

The new graphic object is another arc with a pie arc type and containing a fill 
pattern ®. 

11.2.2.2 Calling UiS$SET-JVRC-TYPE and Using Fill Patterns 

Figure 11-1 describes two ways of closing an arc. 
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Figure 11-1 Closing an Arc 
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Finally, the second part of the program ARC executes and the fill pattern is drawn in 
the pie as shown in Figure 11-2. 


Figure 11-2 Filling a Closed Arc 
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11.2.2.3 Program Development II 

Programming Objective 
To draw thickened lines. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with a title. 

3. Draw two horizontal lines the width of the viewport—one near the bottom of 
the viewport and one near the top of the viewport. 

4. Draw a vertical line connecting the horizontal lines. 

5. Modify the line width attribute in attribute block 0 by a factor of 2. 

6. Repeat steps 4 and 5. 

PROGRAM LINE.WIDTH 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYSSLIBRARY:UISENTRY’ 

INCLUDE ’SYSSLIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0.60.0,30.0.15.0.15.0) 
WD_ID=UIS$CREATE^WINDOW(VD_ID.’SYS$W0RKSTATI0N’.’LINE WIDTH’) 

CALL UIS$PL0T(VD_ID.0.1.0.25.0,60.0,25.0) O 
CALL UIS$PL0T(VD_ID,0,1.0.5.0,60.0,5.0) 0 

CALL UIS$PL0T(VD_ID,0,5.0.5.0,5.0,25.0) 0 

CALL UIS$SET_LINE_WIDTH(VD_ID,0,1,2.0) © 

CALL UIS$PL0T(VD_ID,1,10.0,5.0,10.0,25.0) 0 

CALL UIS$SET_LINE_WIDTH(VD_ID.0,1.4.0) 

CALL UIS$PL0T(VD_ID,1,15.0.5.0,15.0,25.0) 

CALL UIS$SET_LINE_WIDTH(VD_ID.0,1,6.0) 

CALL UIS$PL0T(VD_ID.1,20.0,5.0,20.0,25.0) 

^ CALL UIS$SET_LINE_WIDTH(VD_ID.0,1,8.0) 

CALL UIS$PL0T(VD_ID,1,25.0,5.0,25.0,25.0) 

CALL UIS$SET_LINE_WIDTH(VD_ID,0,1,10.0) 

CALL UIS$PL0T(VD_ID,1,30.0.5.0,30.0,25.0) 

CALL UIS$SET_LINE_WIDTH(VD.ID.0,1.12.0) 

CALL UIS$PL0T(VD_ID.1,35.0,5.0,35.0.25.0) 

CALL UIS$SET_LINE_WIDTH(VD_ID,0,1,14.0) 

CALL UIS$PL0T(VD_ID.1,40.0,5.0.40.0,25.0) 
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CALL UIS$SET_LINE_WIDTH(VD.ID,0,1,16.0) 

CALL UISIPLOT(VD.ID,1,45.0,5.0,45.0,25.0) 

CALL UIS$SET_LINE_WIDTH(VD.ID,0,1,18.0) 

CALL UIS$PLOT(VD.ID,1,50.0,5.0,50.0,25.0) 

CALL UIS$SET.LINE.WIDTH(VD.ID,0,1,20.0) 

CALL UIS$PLOT(VD.ID,1,55.0,5.0,55.0,25.0) 

PAUSE 

END 

Two parallel lines are drawn with normal thickness the width of the display window 
using UIS$PLOT O ©. 

A vertical line of normal thickness is drawn 

Subsequent calls modify the line width attribute O and draw the resulting line @ 
from the line in the lower half of the display window to the line in the upper half of 
the display screen. 

11.2.2.4 Calling UIS$SET-LINE-WIDTH 

Figure 11-3 shows lines are drawn from point to point with increasing thickness. 
Figure 11-3 Line Width 



NOTE: Extremely thick lines should be drawn using UIS$PLOT or UIS$PLOT_ 
ARRAY to and UIS$SET_FILL—PATTERN construct filled rectangles. 
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11.2.2.5 Program Development III 

Programming Objective 

To draw various patterns of thickened dots and dashes. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with title. 

3. Modify the line width attribute to a thickness of 5 pixels. 

4. Draw a solid thick line. 

5. Modify the line style attribute. 

6. Draw the dashed line. 

7. Repeat steps 5 and 6. 

PROGRAM LINE_STYLE 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYSILIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0.20.0.20.0,15.0,6.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.*SYS$W0RKSTATI0N’.’LINE STYLE AND WIDTH’) 

CALL UIS$SET_LINE_WIDTH(VD_ID.O,1,5.0) O 
CALL UISIPLOT(VD_ID.1.1.0,18.0,18.0,10.0) 

CALL UIS$SET_LINE_STYLE(VD_ID,1.1.’FFFFFFFO’X) Q 
CALL UIS$PL0T(VD_ID,1.1.0.14.0.18.0,10.0) 

CALL UIS$SET_LINE_STYLE(VD_ID.1.2,’FOFOFOFO’X) © 

CALL UIS$PL0T(VD_ID,2.1.0,10.0,18.0,10.0) 

CALL UIS$SET_LINE_STYLE(VD_ID.2,3,’90909090’X) O 
CALL UIS$PL0T(VD_ID,3,1.0,6.0,18.0.10.0) 

CALL UIS$SET_LINE_STYLE(VD_ID,3,4,’10010010’X) © 

CALL UIS$PLOT(VD_ID.4.1.0.2.0,18.0,10.0) 

PAUSE 

END 

Different line styles are created by selecting different hexadecimal values in the calls 
to UIS$SET_LINE—STYLE O © © O. The hexadecimal values set bits in the line 
style bit vector, which, in turn, generate a pattern. 
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11 . 2 . 2.6 Calling UIS$SET-LINE-WIDTH and UIS$SET_LINE_STYLE 

When the program LINE—STYLE executes, five lines are drawn. Each line is drawn 
with the same width but different style. The pattern of dots and dashes is determined 
by the value supplied to the line style longword bit vector as shown in Figure 11-4. 

Figure 11-4 Modifying Line Width and Style 



11.2.2.7 Program Development IV 
Programming Objective 

To construct a vertical bar graph. 

Programming Tasks 

1. Load arrays from DATA statements. 

2. Create a virtual display. 

3. Create a display window and viewport with a title. 

4. Draw the x and y axes. 

5. Draw the legend. 

6. Draw the information along the x axis. 

7. Draw the information along the y axis. 

8. Modify the font and fill pattern attributes. 
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9. Draw the vertical bars using the appropriate fill patterns to their proper heights 
using the arrays. 

PROGRAM GRAPH 
IMPLICIT INTEGER(A-Z) 

CHARACTER*4 STRING 

REAL ARRAYl(8),ARRAY2(8),X.X2.HEIGHT.Y O 

DATA ARRAYl /5.0.10.0.12.0,13.0,15.0,20.0,25.0,30.0/ 

DATA ARRAY2 /O.O, 1.0, 2.0, 1.0, 4.0, 9.0,15.0,21.0/ 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(-5.0.-5.0,50.0,50.0,20.0.20.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’,’GRAPH’) 

CALL UIS$SET_LINE_WIDTH(VD_ID,0,16,5.0) © 

CALL UIS$PLOT(VD_ID.16,0,0,0,35.0) © 

CALL UIS$PLOT(VD_ID.16,0,0,45.0,0) O 

CALL UIS$TEXT(VD_ID,0,’U.S. ADULT POPULATION VS. CAR OWNERSHIP’, 
2 10.0,-3.0) © 

c Information along the y axis 

DO 20 I = 1.7 

Y = 5.0 * float (I) © 

N = 25 * I © 

ENCODE (3.10,STRING) N © 

10 FORMAT (13) 

20 CALL UIS$TEXT(VD_ID.0.STRING.-3.0.Y) © 

CALL UIS$TEXT(VD_ID.O.’(in millions)’.-3.0,37.0) 
c Information along the x axis 

DO 40 I = 1,8 

Y = 5.0 * FLOAT (I) 

N = 1900 + (10 * I) 

ENCODE (4.30.string) N 

30 FORMAT (14) 

40 CALL UIS$TEXT(VD_ID.0.string,Y.-1.0) 

CALL UIS$SET_FONT(VD_ID.0,1,’UIS$FILL_PATTERNS’) © 

CALL UIS$SET_FILL_PATTERN(VD_ID,1,1,PATT$C_H0RIZ4_4) © 

CALL UIS$SET_FILL_PATTERN(VD_ID,1,2,PATT$C_GREY12_16) © 

C PLOT POPULATION RECTANGLE 

DO 100 I = 1,8 
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X = 5.0 * FLOAT(I) 

X2 = X + 2.0 
HEIGHT = ARRAYl(I) <E) 

CALL UIS$PLOT (VD.ID.l, X.0.0. X,HEIGHT. X2.HEIGHT, X2,0.0) 

C PLOT CAR RECTANGLE 

X = X + 1.0 

X2 = X + 2.0 

HEIGHT = ARRAY2(I) ® 

CALL UIS$PLOT (VD_ID,2. X.O.O, X.HEIGHT. X2,HEIGHT. X2.0.0) 

100 CONTINUE 

PAUSE 

END 

Two arrays, ARRAYl and ARRAY2 are declared O to store the height of each vertical 
bar in the graph. 

The X and y axes are drawn 0 O. However, a previous call to UIS$SET_LINE_ 
WIDTH 0 has modified the attribute block controlling the appearance of lines. We 
have indicated that we want the width of the lines {x and y axes) to be five times 
wider than normal. 

The legend of the graph is created in a call to UIS$TEXT 0. 

The y world coordinate values are computed 0 as multiples of 5 where I represents 
the number of passes through the DO loop. The adult population numbers will be 
written at these intervals. 

The numbers along the y axis are computed and stored in the variable N 0 and then 
returned to the variable string as character string constants 0 0. 

Before you create the rectangles to represent the eight vertical bars in the graph, 
you must specify the fill pattern—either an existing one or a new pattern. Because 
the font attribute has not been modified in our program, UIS$SET_FONT uses a 
copy of attribute block 0 to set the font attribute 0. In this case, specify a font ID 
UIS$FILL—PATTERNS to indicate that you want the file of fill patterns. 

Now we must set the fill pattern attribute using UIS$SET_FILL—PATTERN. The 
program must use two different fill patterns to contrast adult population vertical bars 
from automobile vertical bars 0 0 . 

The values previously assigned to each element of ARRAYl and ARRAY2 control the 
height of the vertical bars © 0 . 
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11.2.2.8 Calling UIS$SET-FONT and UIS$SET-FILL-PATTERN 

If you ran the program GRAPH now it would produce the vertical bar graph as 
shown in Figure 11-5. 

Whenever you create a fill pattern, you must include UIS$SET_FONT and UIS$SET— 
FILL—PATTERN. The positional order of the calls is important. Calls to UIS routines 
that modify an attribute block must precede the call that creates the graphic object. 

In order to produce the desired change in the resulting graphic object, the 
accompanying call to UIS$PLOT must reference the same output attribute block 
number. 

11.2.3 Using the Windowing Attribute 

The clipping rectangle attribute modifies the size of the viewable portion of the 
virtual display. It does not resize the display window or display viewport. 

11.2.3.1 Programming Options 

There is only one attribute, namely the clipping attribute, that controls what is visible 
through the display window and viewport. 

Clipping Rectangle 

Maybe you need to restrict drawing in the virtual display to a specified rectangle. 
You can create clipping rectangles that view a portion of your original display 
window using UIS$SET—CLIP. These rectangles are not display windows, but they 
can be used to partition your virtual display into discrete areas. They create an 
environment within your virtual display that can be visited whenever you reference 
the appropriate attribute block that contains a modified clipping rectangle attribute. 
Note that the clipping rectangle merely restricts drawing to an area. It does not 
change mapping between the virtual display and the display window. 

11.2.3.2 Program Development 

Programming Objective 

To construct three clipping rectangles. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with a title. 

3. Choose a font and modify the font attribute. 

4. Specify a clipping rectangle and modify the clipping attribute. 

5. Draw a line of text using the modified font attribute with clipping disabled. 

6. Draw a line of text using the modified font attribute with clipping enabled. 
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7. Repeat steps 3 through 6 two more times. 

Logical names have been defined for font file names. 

PROGRAM CLIP 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0,0.0,45.0,45.0,15.0,5.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$W0RKSTATI0N’,’CLIPPING’) 

CALL UIS$SET_F0NT(VD_ID.0,1,’MY_F0NT_5’) O 

CALL UIS$SET_CLIP(VD_ID.1,5,1.0,1.0,10.0,40.0) © 

CALL UIS$TEXT(VD_ID.l.’Still waters run deep’.0.0,40.0) 

CALL UIS$NEW_TEXT_LINE(VD_ID,1) 

CALL UIS$TEXT(VD_ID.5.’Still waters run deep’) 

CALL UIS$SET_F0NT(VD_ID.0.2.’MY_F0NT_6’) O 
CALL UIS$NEW_TEXT_LINE(VD_ID.2) 

CALL UIS$SET_CLIP(VD_ID.2,6.15.0,15.0.35.0.40.0) O 

CALL UIS$TEXT(VD_ID,2,’The sleepy fox has seldom feathered breakfasts’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.2) 

CALL UIS$TEXT(VD_ID,6,’The sleepy fox has seldom feathered breakfasts’) 

CALL UIS$SET_F0NT(VD_ID.0.3,’MY_F0NT_10’) O 

CALL UIS$NEW_TEXT_LINE(VD_ID.3) 

CALL UIS$SET_CLIP(VD_ID.3,7.7.0.5.0.30.0.40.0) © 

CALL UIS$TEXT(VD_ID,3,’When the wind is west, the fish bite best’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.3) 

CALL UIS$TEXT(VD_ID,7,’When the wind is west, the fish bite best’) 

PAUSE 

END 

Three fonts O © © are used to illustrate clipping rectangles. The call to UIS$SET_ 

CLIP modifies the attribute block that controls clipping rectangle size. Each call to 
UIS$SET_CLIP © O © specifies a different clipping rectangle size. Although, only 
one display viewport has been specified in this program, UIS$SET_CLIP creates 
many compartments within the display window. 
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11.2.3.3 Calling UIS$SET-CLIP 

Your workstation screen would display the graphic objects shown in Figure 11-6. 

Figure 11-6 Clipping rectangles 


clipping 


Still waters run deep 
>till 

The sleepg fox has seldom feathered breakfasts 

.dom feathered breakfasts 

Uhen tlie wind is west, tTie fisli bite best 
» wind is west, tbe fisb I 



As you can see, UIS$SET_CLIP has altered the display window of the last three 
lines. Only portions of each lines are now visible. 















Chapter 12 
Inquiry Routines 


12.1 Overview 

Inquiry routines return program-specific information to the application; in this way, 
they behave like functions. However, unlike functions which return a single value 
through a return variable, certain UIS inquiry routines return data in two or more 
parameters in the argument list. This data can range from current attribute settings 
to current state of the pointer buttons. Your application program can use this data to 
establish context during program execution, to check for true or false conditions, or 
to verify that requested operation has been performed. 


12.2 Inquiry Routines—How to Use Them 

Many common graphics application program rely on program-specific data such as 
the position of pointer devices or the font size and so forth. Inquiry routines return 
such data to the program. The data can be used as input to the application as you 
see fit. Such routines are more properly termed functions when used with high-level 
programming languages. 

12.2.1 Using Inquiry Routines 

Generally, UIS routines in the form UIS$GET_xxxx return information to the 
application program. Some of these routines behave like functions and return 
a single value to the program, while others return more than one value in the 
argument list. In any case, these routines obtain data about text and font size, 
windows, keyboard attributes, pointer position, and attribute settings. Such data can 
be used as input to subsequent routines. 
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12.2.1.1 Programming Options 

Your application program can request the following types of application-specific 
information: 

• Color information 

• Display list information 

• Graphics and text attributes 

• Keyboard and pointer characteristics 

• Windowing information 

The inquiry routines are grouped functionally in Table 12-1, 


Table 12-1 Inquiry Routines 


Inquiry 

Information Returned 

Color^ 

UIS$GET_BACKGROUND_INDEX 

UIS$GET_COLOR 

UIS$GET_COLORS 

UIS$GET_HW_COLOR_INFO 

UIS$GET_INTENSITIES 

UIS$GET_INTENSITY 

UIS$GET_VCM_ID 

UIS$GET_WRITING-INDEX 

UIS$GET_WRITING_MODE 

UIS$GET_WS_COLOR 

UIS$GET_WS_INTENSITY 

Background color index 

Single RGB color value in a color map entry 

RGB color values 

Hardware color map characteristics 

Intensity values in virtual color map 

Single intensity value in a virtual color map entry 
Virtual color map identifier 

Writing color index 

Writing mode 

Workstation standard color 

Workstation standard color intensity 

-X- 

Color Conversion 

UIS$HLS_TO_RGB 

UIS$HSV_TO_RGB 

UIS$RGB_TO_HLS 

UIS$RGB_TO_HSV 

Converts HLS values to RGB color values 

Converts HSV values to RGB color values 

Converts RGB values to HLS color values 

Converts RGB values to HSV color values 


^See Chapter 16 for more information about color and intensity inquiry routines. 
^See Chapter 16 for more information about color conversion routines. 
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Table 12-1 (Cont.) Inquiry Routines 


Inquiry 

Information Returned 

Display List 

UIS$FIND_PRIMITIVE 

UIS$FIND_SEGMENT 

UIS$GET_CURRENT_OBJECT 

UIS$GET_NEXT_OBJECT 

UIS$GET_OBJECT_ATTRIBUTES 

UIS$GET_PARENT_SEGMENT 

UIS$GET_PREVIOUS_OBJECT 

UIS$GET_ROOT_SEGMENT 

Identifier of the next primitive in the specified 
rectangle 

Segment identifier of the next segment that contains 
objects in a specified rectangle 

Identifier of last object drawn in virtual display 
Identifier of next object 

Object type 

Parent segment identifier 

Identifier of the previous object 

Root segment identifier 

Graphics 

UIS$GET_ARC_TYPE 

UIS$GET_FILL .PATTERN 

UIS$GET_LINE .STYLE 

UIS$GET.LINE .WIDTH 

Arc type used to close arc 

Fill pattern index and status * 

Line style vector 

Line width in pixels or as a world coordinate x- 
coordinate width 

Keyboard and Pointer 

UIS$GET_J^BS.POINTER.POS 

UIS$GET.BUTTONS 

UIS$GET.KB_JS^TTRIBUTES 

UIS$GET.POINTER.POSITION 

UIS$GET.TB.INFO 

UIS$GET.TB.POSITION 

UIS$TEST_KB 

Absolute position of the pointer 

State of the pointer device buttons 

Keyboard characteristics 

Position of pointer in world coordinates 

Returns the characteristics of the tablet 

Position on tablet in centimeters 

Successful or unsuccessful connection between virtual 
and physical keyboard 

Text 

UISSGET-J^LIGNEDJ’OSITION 

UIS$GET.CHAR.ROT 

UIS$GET.CHAR.SIZE 

World coordinates along the x-height of the current 
position of the next character 

Angle of character rotation in degrees 

If character scaling is enabled and the scaling factors 
used 
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Table 12-1 (Cent.) Inquiry Routines 

Inquiry Information Returned 

Text 

UIS$GET_CHAR_SLANT Angle of character slant in degrees 

UIS$GET_CHAR_SPAC1NG Character and line spacing factor 

U1S$GET_F0NT Font name 

UlS$GET_FONT_ATTRlBUTES All font character characteristics 

UlS$GET_FONT_SlZE Font size in centimeters 

UIS$GET_LEFT_MARGIN World coordinate of left margin 

UlS$GET_POSlT10N World coordinates of text baseline 

UlS$GET_TEXT_FORMATTING Formatting mode 

U1S$GET_TEXT_MARG1NS Text margin settings for a line of text 

U1S$GET_TEXT_PATH Direction of text drawing 

UlS$GET_TEXT_SLOPE Angle of the text baseline in degrees 

U1S$MEASURE_TEXT Proportions of text in world coordinates 


Windowing 

U1S$GET_CL1P 

U1S$GET_D1SPLAY_S1ZE 

UlS$GET_VlEWPORT_lCON 

U1S$GET_V1EWP0RT_P0S1T10N 

UlS$GET_VlEWPORT_SlZE 

U1S$GET_V1S1B1L1TY 

UlS$GET_WlNDOW_ATTRlBUTES 

UlS$GET_WINDOW_SIZE 


Clipping rectangle 

Display screen dimensions in centimeters 
Whether or not the icon is occluded 
Absolute position of display viewport on display 
screen 

Dimensions of the display viewport in centimeters 
Whether or not viewport is occluded 
Window and viewport attributes 

Dimensions of the display window in world 
coordinates 
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12 . 2 . 1.2 Program Development I 

Programming Objective 

To return font and viewport information in order to center text. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with a title. 

3. Obtain the font size for a particular character string, viewport size, and display 
screen size. 

4. Choose a font and modify the font attribute block. 

5. Draw a line of centered text in the viewport using the modified font attribute and 
the information from the inquiry routines. 

6. Print the inquiry information in the terminal emulation window. 

7. Repeat steps 3 through 6. 

The font file names used in this program are logical names. 

PROGRAM CENTER 
IMPLICIT INTEGER(a-z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY;UISUSRDEF’ 

REAL F.WIDTH.F.HEIGHT,D.WIDTH,D.HEIGHT 
REAL V_WIDTH.V_HEIGHT 

VD_ID1=UIS$CREATE_DISPLAY(1.0.1.0,15.0,2.0.15.0.2.0) 
WD_ID1=UIS$CREATE_WIND0W(VD_ID1,’SYS$W0RKSTATI0N’.’CENTERED TEXT’) 

* CALL UIS$GET_F0NT_SIZE(’MY_F0NT_7’,’Time has wings’. 

2 F_WIDTH,F_HEIGHT) O 

CALL UIS$GET_DISPLAY_SIZE(’SYS$W0RKSTATI0N’,D.WIDTH.D_HEIGHT) O 
CALL UIS$GET_VIEWP0RT_SIZE(WD_ID1.V_WIDTH.V_HEIGHT) © 

CALL UIS$SET_F0NT(VD_ID1.0.7,’MY_F0NT_7’) O 
CALL UIS$TEXT(VD_ID1.7.’Time has wings’, 

2 (V_WIDTH-F_WIDTH)/2. 

2 V.HEIGHT) © 

PAUSE 

PRINT 50 

50 FORMAT(TIO,’FIRST LINE’.T39.’WIDTH’.T51.’HEIGHT’) 

PRINT 75 

75 FORMAT (T2,’-’, 

2 >->) 
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PRINT 100, F.WIDTH, F.HEIGHT 
100 FORMAT(T2The dimensions of the font are:’, 

2 T39,f5.2.T46.’cm.’.T51.f5.2.T58,’em.’) 

PRINT 150,D_WIDTH.D_HEIGHT 

150 FORMAT(T2,’The dimensions of the display are:’, 

2 T39.f6.2.T46.’cm.’.T51.f6.2.T58.’em.’) 

PRINT 200.V.WIDTH.V.HEIGHT 

200 FORMAT(T2,’The dimensions of the viewport are;’, 

2 T39,f6.2,T46.’em.’.T51,f6.2,T58,’em.’) 

CALL UIS$SET_FONT(VD_ID1.7.8.’MY_F0NT_5’) ® 

CALL UIS$MEASURE_TEXT(VD_ID1.8.’four seasons’. 

2 F_WIDTH.F_HEIGHT) 

CALL UIS$NEW_TEXT_LINE(VD_ID1.8) 

CALL UIS$TEXT(VD_ID1.8.’four seasons’. 

2 (V_WIDTH-F_WIDTH)/2.(V_HEIGHT-F_HEIGHT)) O 

TYPE *.’ ’ 

PRINT 550 

550 FORMAT(TIO.’SECOND LINE’.T39.’WIDTH’,T51.’HEIGHT’) 

PRINT 575 

575 FORMAT (T2.’------’ 

2 ’-’) 

PRINT 610. F.WIDTH, F.HEIGHT 
610 FORMAT(T2.’THE DIMENSIONS OF THE FONT ARE:’, 

2 T39.f5.2,T46,’em.’,T51.f5.2.T58.’em.’) 

PRINT 700.D_WIDTH,D_HEIGHT 

700 FORMAT(T2,’The dimensions of the display are:’, 

2 T39,f6.2.T46,’em.’,T51.f6.2,T58,’em.’) 

PRINT 800,V_WIDTH,V_HEIGHT 

800 FORMAT(T2,’The dimensions of the viewport are:’, 

2 T39,f6.2,T46.’em.’,T51,f6.2,T58,’em.’) 

PAUSE 

END 

The three inquiry functions UIS$GET_FONT_SIZE, UIS$GET_DISPLAY_SIZE, 
and UIS$GET_VIEWPORT_SIZE are called O O O. Each function returns data to 
uniquely specified variables within its argument list. 

A logical name is defined O ® to represent the 31-character font file name. The 
first call to UISSTEXT 0 places a text string in the window. The starting position for 
creating text is calculated from the expression in the argument list. VAX FORTRAN 
allow arithmetic expressions as arguments.® If your application is written in a 
programming language other than VAX FORTRAN, please refer to the appropriate 
language reference manual. 
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In order to center the text in this window, we subtracted the length of the text from 
the total width of the viewport and divided the result by 2. The distance of the text 
from the lower border of the window (the y coordinate) is equal to the value of the 
variable V—height, the height of the display viewport. 

12.2.1.3 Invoking UIS$GET_FONT_SIZE, UIS$GET_DISPLAY_SIZE, and 
UIS$GET_VIEWPORT_SIZE 

If you ran this program now, your workstation screen would display graphic objects 
as shown in Figure 12-1. 


Figure 12-1 Centering Text 
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Note that output from the FORTRAN PRINT or TYPE statement is not displayed in 
the window we have created. The TYPE and PRINT statements are equivalent to 
the logical names FOR$TYPE and FOR$PRINT which translate to the logical name 
SYS$OUTPUT. Only UIS$TEXT can write text to a virtual display. 

12.2.1.4 Program Development II 

Programming Objective 

To construct a pie graph illustrating the operating budget of a small New England 
town. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport with a title. 

3. Choose a font and modify the font attribute. 

4. Print the title of the graph using the modified font attribute, 

5. Obtain font information. 

6. Modify the arc type attribute. 

7. Choose a fill pattern and modify the font attribute and the fill pattern attribute. 

8. Draw an arc using the modified fill pattern attribute. 

9. Draw part of the legend to appear below the pie graph. 

10. Obtain and print arc type and fill pattern information. 

11. Repeat steps 6 through 9. 

PROGRAM PIE_GRAPH 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY;UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

CHARACTER*32 BUFFERDESC 
L0GICAL*4 FILL.ENABLED 

VD_ID=UIS$CREATE_DISPLAY(-3.0,-3.0,25.0,25.0.15.0,15.0) 
WD_ID=UIS$CREATE_WIND0W(VD_ID.’SYS$W0RKSTATI0N’,’PIE GRAPH’) 

CALL UIS$SET_F0NT(VD_ID,0,9,’MY_F0NT_10’) 

CALL UISSTEXT(VD_ID,9,’OPERATING BUDGET’.6.0,24.0) 

CALL UIS$TEXT(VD_ID.9.’TOWN OF GREENWICH, MASS.’.4.0,22.0) 

CALL UIS$GET_F0NT(VD_ID.9,BUFFERDESC.LENGTH) O 


PRINT 10.BUFFERDESC 

10 FORMAT(T2.’THE FONT NAME IS’,T20,A31) © 
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PRINT 11.LENGTH 

11 FORMAT(T2.’THE LENGTH OF THE FONT NAME IS T33.13.T37CHARACTERS’) 

CALL UIS$SET_ARC_TYPE(VD_ID.0,1,UIS$C_ARC_PIE) @ 

CALL UIS$SET_FONT(VD_ID.1.1.’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD_ID.1.1.PATT$C_BRICK_DOWNDIAG) 

CALL UIS$CIRCLE(VD_ID.1,10.0,10.0.8.0.0.0,50.0) 
call uis$plot(vd.id,1,0.0,0.0,2.0,0.0,2.0,-1.0, 

2 0.0,-1.0,0.0,0.0) 

call uisStext(vd_id,0,’Fire’,3.0,0.0) 

ARC_TYPE=UIS$GET_ARC_TYPE(VD_ID.1) O 

FILL_ENABLED=UIS$GET_FILL_PATTERN(VD_ID,1.INDEX) 0 

PRINT 15.ARC_TYPE 

15 FORMAT(T2.’THE ARC TYPE IS’.T25,I1) @ 

PRINT 20.FILL_ENABLED 

20 FORMAT(T2.’IS THE FILL PATTERN ENABLED?’.T32.LI) 

CALL UIS$SET_FONT(VD_ID.1.2.’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD.ID,2.2,PATT$C_D0WNDIAG4_4) 

CALL UIS$CIRCLE(VD_ID.2,10.0,10.0.8.0,50.0,95.0) 

CALL UIS$PLOT(VD_ID.2.10.0,0.0,12.0.0.0,12.0,-1.0, 

2 10.0,-1.0.10.0,0.0) 

CALL UIS$TEXT(VD.ID,0.’Sanitation’,14.0,0.0) 

CALL UIS$SET_F0NT(VD_ID.2.3,’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD.ID,3,3,PATT$C_H0RIZ2_6) 

CALL UIS$CIRCLE(VD_ID,3.10.0,10.0,8.0,95.0,165.0) 

CALL UIS$PL0T(VD_ID.3.0.0,-2.0,2.0,-2.0,2.0.-3.0. 

2 0.0,-3.0,0.0,-2.0) 

CALL UIS$TEXT(VD_ID.O,’Police’,3.0,-2.0) 

CALL UIS$SET_F0NT(VD_ID,3,4,’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD_ID,4,4,PATT$C_GREY4_16D) 

CALL UISICIRCLE(VD_ID,4,10.0,10.0.8.0.165.0.360.0) 

CALL UIS$PLOT(VD_ID,4.10.0,-2.0,12.0,-2.0,12.0,-3.0, 

2 10.0,-3.0,10.0,-2.0) 

CALL UISSTEXT(VD_ID,0,’Schools’.14.0,-2.0) 

PAUSE 

END 

The program PIE—GRAPH returns information about the heading of the graph. A 
call to UIS$GET—FONT O identifies the font and its length 0. The font 
MY—FONT—IO is a logical name for a 31-character font file name. 

Attribute block 1 contains the modified arc type attribute 0. When a new section of 
the arc is drawn, it will have a pie arc type which enables fill pattern. 
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Arc type information is returned in the variable arc—type O. 

A call to UIS$GET__FILL—PATTERN © tests whether fill patterns are enabled. Fill 
pattern information is returned in the variable fill—enabled © as a Boolean value. 

12.2.1.5 Invoking UIS$GET_ARC_TYPE, UIS$GET_FILL-PATTERN, and 
UIS$GET_FONT 

The program PIE—GRAPH draws a pie graph containing four fill patterns and 
requests and displays certain program-specific information as shown in Figure 12-2. 
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Figure 12-2 Pie Graph 
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Chapter 13 

Display Lists and Segmentation 


13.1 Overview 

As you have seen so far, you can use your applications to construct different types 
of graphic objects. Programs containing code for complex graphic objects can pose a 
problem because of their sheer size. In any case, the increasing complexity of your 
displays will require that you understand display list concepts. This chapter discusses 
the following topics: 

• Creating and searching segments 

• Editing and walking the display list 

• Disabling display lists 

• Creating UIS metafiles 

• Attaching private data to graphic objects 

You can view creating complex objects as an opportunity to reduce the complexity of 
your graphic object and to modularize your coding through the use of segmentation. 


13.2 Display Lists 

UIS constructs a display list of encoded commands for graphics. These display lists 
remain resident in memory for use by UIS routines. Figure 13-1 shows the format of 
an entry in the display list. 
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Figure 13-1 Binary Encoded Instruction 
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UIS signals an error if it encounters an invalid opcode. 

Whenever you call UIS routines to create graphic objects or modify attribute blocks, 
you have added an entry to a display list. Only one display list exists for each virtual 
display. 

A display list is a device-independent encoding of the exact contents of the virtual 
display. UIS maintains display lists for the folloAving purposes: 

• Automatic management of panning, zooming, resizing, and duplication of display 
windows 

• High resolution printing of physical and virtual displays 

• Structuring and manipulation of graphic objects in the virtual display 

• Storing the contents of the virtual display in a buffer for later reexecution 


13.3 Segments 

A segment consists of calls to UIS graphics and text routines and any nested 
segments. Segments are created explicitly with a call to UIS$BEGIN—SEGMENT, 
and are terminated with a call to UIS$END_SEGMENT. A complex display list is a 
hierarchy of nested segments. 

Any segment or output (graphic and text) routine not contained in an explicitly 
created segment is part of a top-level root segment. 

The primary purpose of segmentation of graphics routines is to facilitate 
transformations—scaling, rotation, and translation. Segmentation also modularizes 
attributes. Complex graphic objects can be constructed in parts where each logical 
grouping of display list entries is contained within a segment. Such segments could 
be transformed or displayed individually and independently of the rest of the object. 
Changing attributes within a segment will not affect the attribute settings of a 
higher-level segment. 
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For example, a house, a barn, and landscape are constructed as three logical 
groupings, or subpictures of a complex display. Each subpicture is a segment of 
appropriate UlS routines. You could manipulate all three subpictures independently 
of each other. 

Figure 13-2 shows a tree diagram of a display list containing nested segments. The 
diagram should be read from left to right and downward whenever a segment is 
encountered until there are no more segments. Read each level to the right and 
move upward to the next level where you left off. 

Figure 13-2 Nested Segments 
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13.3.1 Identifiers and Object Types 

There are many types of UIS identifiers—for example, virtual display identifier, 
virtual keyboard identifier, transformation identifier, and so on. Identifiers allow 
your application to reference and manipulate internal objects. Managing the display 
list involves (1) traversing the display list downward object by object, (2) searching 
a segment, and (3) traversing upward through the segment path. 
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Segments 

Each segment has a unique identifier returned by UIS$BEGIN_SEGMENT. If no 
segments were explicitly declared using UIS$BEGIN—SEGMENT, then the root 
segment has a unique identifier that can be used to manipulate the display list. 

Objects 

Every object in the virtual display has an object identifier. However, not all routines 
return identifier explicitly. Object and segment identifiers are useful in walking and 
editing the display list. They are used as reference points within complex display 
lists. 

The identifier may not always be part of the calling sequence and sometimes must 
be returned using another UIS routine. For example, none of the graphics and text 
routines return identifiers explicitly. You can obtain the identifier using one of the 
routines listed in the table. The following table lists identifiers and the UIS routines 
that return them. 


Graphic Object 

Identifier 

Routine 

Segment 

seg_id 

UIS$BEGIN-SEGMENT^ 

Root segment 

root—id 

UIS$GET-ROOT-SEGMENT 

Parent segment 

parent—id 

UIS$GET-PARENT-SEGMENT 

Graphic objects 

prev—id 

UIS$GET-PREVIOUS-OBJECT 


current—id 

UIS$GET-CURRENT-OBlECT 


next—id 

UIS$GET-NEXT-OBJECT 

^UIS$BEGIN_SEGMENT returns the segment identifier in a return variable, seg—id. 


Object Types 

Even though you can manipulate the display list using segment and object identifiers, 
you still need to further identify those objects within a segment. You need to know 
exactly what type of object the display list entry is. The object type refers to the way 
UIS categorizes graphic objects and segments. There are six object types represented 
by the symbols listed here. 
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Symbol 

Graphic Object 

UIS$C_OBJECT_SEGMENT 

New segment 

UIS$C_OBJECT_PLOT 

Point, line, or polygon 

UIS$C_OBJECT_TEXT 

Text 

UIS$C_OBJECT_ELLIPSE 

Ellipse or circle 

UIS$C_OBJECT_IMAGE 

Raster image 

UIS$C_OBJECT_LINE 

Unconnected lines 


UIS$GET_OBJECT_ATTRIBUTES returns object type information. 

13.3.2 Programming Options 

The behavior of display lists and segmentation can best be described separately. 
From the options available below, we will construct two programs. The first program 
illustrates disabling display lists, while the second demonstrates walking the display 
list. 

Creating Segments 

You can create an unlimited number of segments explicitly with UIS$BEGIN_ 
SEGMENT and UIS$END_SEGMENT. UIS returns a unique identifier for each 
newly created segment that can be used by appropriate UIS routines to locate and 
edit segments. In addition, you can nest segments within segments. 

NOTE: If UIS$BEGIN_SEGMENT is called and no graphics and text routines 
are called before UIS$END_SEGMENT is called, the segment is deleted and the 
identifier returned is no longer valid. If you wish to create an empty segment, call 
UIS$BEGIN_SEGMENT followed by UIS$PRIVATE. This sequence places private 
data in the segment and UIS$END_SEGMENT will not consider the segment empty. 

Enabling and Disabling Display Lists 

Disabling a display list prevents new additions from being added to the list. Display 
lists are enabled and disabled explicitly with UIS$ENABLE_DISPLAY_LIST and 
UIS$DISABLE_DISPLAY_LIST. You can enable and disable a display list any 
number of times within a program. However, to see the results of disabling a display 
list, you must execute the display list. UIS$EXECUTE can be used to execute the 
display list. The following routines may also cause the display list to be executed. 
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Routine 


Function 


UIS$CREATE_WINDOW 

uis$delete_obiectL5 

UISSEXECUTE^’^ 

UIS$M0VE_AREA^’5 

UISSMOVE-WINDOW'^’^ 


Creates a display window and viewport 
Deletes an object in the virtual display 
Executes the display list 

Moves a portion of the virtual display another part of the 
virtual display 

Redefines the display window coordinate space. 


^UIS$DELETE—OBJECT executes the display list only when the object to be deleted occluded another 
object. 

^U1S$EXECUTE executes the entire display list, if buflen and bufaddr are not specified. 

^UlS$MOVE_AREA executes the display list only if the specified source and destination rectangles lie 
within a display window. 

^UlS$MOVE_WINDOW executes the display list only if the window size is changed. 

^This routine checks display list flags. 


The position of UIS$DIS ABLE-DISPLAY-LIST and UIS$EN ABLE-DISPLAY- 
LIST in your program is important. If the display list is disabled after the display 
list is executed, the viewport displays all the graphic objects drawn in the virtual 
display. If the display list is disabled before one of the routines listed above is 
called, the viewport displays none of the graphic objects created between calls to 
UIS$DISABLE-DISPLAY-LIST and UIS$EN ABLE-DISPLAY-LIST. No binary 
instructions were added to the display list. 

Walking the Display List 

You can traverse, or walk the entire display list from top to bottom and from object 
to object using UIS$GET-ROOT-SEGMENT and UIS$GET-NEXT-OBJECT. 

Searching a Segment 

If the display list contains segments, you can search the contents of any segment in 
the display list with UIS$GET-NEXT-OBJECT. 

Traversing the Segment Path 

Because the root segment is the ultimate parent segment, every nested segment has 
a parent segment. The root segment acts as the parent for all level-one segments. 
See Figure 13-2. A segment identifier identifies the beginning of each segment in 
a display list. The segment identifiers within a display list comprise its segment 
path. You can traverse the segment path from the innermost segment outward with 
UIS$GET-PARENT-SEGMENT. 
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13.3.3 Program Development I 

Programming Objective 

To disable a display list. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Disable the display list. 

4. Draw some graphic objects in the virtual display. 

5. Reenable the display list. 

6. Draw some graphic objects in the virtual display. 

7. Create a second display window and viewport. 

PROGRAM LIST 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(-1.0.-1.0,50.0,50.0.10.0,10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’,’MORE’) O 

c Disable the display list 

CALL UIS$DISABLE_DISPLAY_LIST(VD_ID) O 

c Draw the graphic objects 

CALL UIS$CIRCLE(VD_ID,0,15.0,15.0,5.0) 

CALL UIS$CIRCLE(VD_ID.0.5.0.5.0,5.0) 

CALL UIS$PLOT(VD_ID.0,27.0,17.0,35.0,17.0.35.0,24.0,27.0,24.0, 

2 27.0,17.0) 

CALL UIS$CIRCLE(VD_ID.0,35.0.35.0,8.0) 

CALL UIS$PLOT(VD_ID.0.5.0,30.0,15.0.30.0,10.0,40.0,5.0,30.0) 
PAUSE 

c Reenable the display list 

CALL UIS$ENABLE_DISPLAY_LIST(VD_ID) ® 
c Draw circle and triangle 

CALL UIS$CIRCLE(VD_ID,0,33.0,35.0,8.0) O 

CALL UIS$PLOT(VD_ID.0,7.0,31.0,17.0,31.0,12.0,41.0,7.0,31.0) 0 

WD_ID1=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’.’LESS’) 0 

PAUSE 

END 
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Initially, a display window and viewport labelled MORE are created O. The world 
coordinate range of the window defaults to that of the virtual display. 

The display list is disabled ©. 

Five graphic objects are drawn in the virtual display—three circles, a triangle, and a 
square. Even though all five objects appear in the viewport MORE, no entries are 
added to the display list. 

After the PAUSE statement, the display list is reenabled 0 and a triangle and another 
circle are drawn O ©. 

Remember the first call to UIS$CREATE—WINDOW was executed before the display 
list was disabled. Therefore, objects drawn in the virtual display and within the 
display window are displayed in the viewport, but are not added to the display list. 

Finally, the second display window and viewport labelled LESS are created 0. The 
display list is executed and all objects except those included within the disable-enable 
request appear in the viewport LESS. 

13.3.3.1 Calling UIS$DISABLE-DISPLAY-LIST and UIS$ENABLE-DISPLAY-LIST 

When the program executes, the viewport MORE is displayed first as shown in 
Figure 13-3. 

Figure 13-3 Disabling a Display List 
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Type CONTINUE at the dollar sign prompt ($). Figure 13-4 shows both viewports 
MORE and LESS. Note that the second call to UIS$CREATE—WINDOW executes the 
display list. 

Figure 13-4 After Display List Execution 




13.3.3.2 Program Development II 

Programming Objective 

To traverse the entire display list and examine each object type. 
Programming Tasks 

1. Create a virtual display. 

2. Draw graphic objects in the virtual display. 

3. Print headings for the output in the emulation window. 

4. Obtain the identifier of the root segment. 

5. Walk downward through the display list. 

6. Examine each object type and place its identifier in one of five arrays. 
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Figure 13-5 Tree Diagram—Program WALK 
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The program WALK draws objects in a virtual display and then identifies each object 
by walking the entire display list and examining the various object type values. 

The program also shows how you can collect and store object identifiers according 
to object type. If you intend to run program WALK, the subroutine DETERMINE 
should be compiled as a separate module and linked with WALK. 

PROGRAM WALK 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE 'SYS$LIBRARY:UISUSRDEF’ 

COMMON NEXT.IDl.TYPEl O 

VD_ID1=UIS$CREATE_DISPLAY(0.0,0.0.40.0.40.0,20.0.20.0) © 

C Draw objects in virtual display 

CALL UIS$CIRCLE(VD.IDl.0,15.0,15.0,6.0) 

CALL UIS$PL0T(VD_ID1.0,1.0,1.0,20.0,1.0,20.0.8.0.1.0,1.0) 

CALL UIS$PL0T(VD_ID1.0,20.0,20.0,40.0,20.0,30.0,35.0,20.0, 

2 20 . 0 ) 

CALL UIS$PL0T(VD_ID1,0,3.0,25.0,13.0,25.0,13.0,35.0, 

2 3.0,35.0,3.0,25.0) 

CALL UIS$TEXT(VD_ID1,0,’The footsteps of fortune are slippery’, 

2 0.0,38.0) 

CALL UIS$NEW_TEXT_LINE(VD_ID1.0) 

CALL UIS$TEXT(VD_ID1,0,’Mirth without measure is madness’) 

PRINT 10 

10 FORMAT(T2.’DISPLAY LIST ELEMENTS’) 

PRINT 20 

20 FORMAT (Tl.’-’) 

PRINT 30 

30 FORMAT(T2.’IDENTIFIER’.T17.’OBJECT TYPE’) 

R00T_ID1=UIS$GET_R00T_SEGMENT(VD_ID1) O 

NEXT.IDl = ROOT.IDl 


c Walk the display list 
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DO WHILE (NEXT.IDl .NE. 0) O 

TYPE1=UIS$GET_0BJECT_ATTRIBUTES(NEXT_ID1) @ 

CALL DETERMINE © 

NEXT_ID1=UIS$GET_NEXT_0BJECT(NEXT.IDl) O 

ENDDO ® 

WD_ID1=UIS$CREATE_WIND0W(VD_ID1.’SYS$WORKSTATION’) © 

PAUSE 

END 

SUBROUTINE DETERMINE © 

IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

INTEGER+4 SEG_ARRAY(6).PL0T_ARRAY(6).TEXT_ARRAY(6).ELLIP_ARRAY(6) ® 
INTEGER*4 LINE(6).IMAGE(6) © 

DATA H.I.J.K.L,M/1.1.1.1,1.1/ © 

COMMON NEXT.IDl.TYPEl © 

IF (TYPEl .EQ. UIS$C_OBJECT_SEGMENT) THEN © 

SEG_ARRAY(H)= NEXT.IDl 
PRINT 40.SEG.ARRAY(H).TYPEl 
40 FORMAT(T2,16.T19.I1.T24,’SEGMENT’) 

H = H + 1 
END IF 

IF (TYPEl .EQ. UIS$C_OBJECT_PLOT) THEN © 

PLOT_ARRAY(I) = NEXT_ID1 
PRINT 50.PL0T_ARRAY(I).TYPEl 
50 F0RMAT(T2.I6.T19.I1.T24.’PLOT’) 

1 = 1 + 1 
END IF 

IF (TYPEl .EQ. UIS$C_OBJECT_TEXT) THEN © 

TEXT_ARRAY(J) = NEXT.IDl 
PRINT 55.TEXT_ARRAY(J).TYPEl 
55 FORMAT(T2.16.T19.I1.T24.’TEXT’) 

J = J + 1 
END IF 

IF (TYPEl .EQ. UIS$C_OBJECT_ELLIPSE) THEN © 

ELLIP_ARRAY(K) = NEXT.IDl 
PRINT 60,ELLIP.ARRAY(K).TYPEl 
60 F0RMAT(T2.I6.T19.I1,T24,’ELLIPSE’) 

K = K + 1 
ENDIF 
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IF (TYPEl .EQ. UIS$C_OBJECT_LINE) THEN ® 

LINE(L) = NEXT.IDl 
PRINT 70,TEXT.LINE(L).TYPEl 
70 FORMAT(T2.16.T19.I1.T24.’NEW TEXT LINE’) 

L = L + 1 
END IF 

IF (TYPEl .EQ. UIS$C_OBJECT_IMAGE) THEN ® 

IMAGE(M) = NEXT_ID1 
PRINT 80.IMAGE(M).TYPEl 
80 F0RMAT(T2.I6.T19.I1.T24.’IMAGE’) 

M = M + 1 
ENDIF 

RETURN 

END 

The variables next—idl and typel are used in both the main program and the 
subroutine DETERMINE, The COMMON statement ensures access to data stored 
in both locations by both the main program and the subroutine O 

A virtual display is created ©. As objects are drawn in the virtual display, display 
list entries in the form of encoded binary data identifying the particular objects are 
added to the display list. Only one display list is created for each virtual display. 

Because the entire display list is to be traversed, the root segment will be the starting 
point and its identifier must be returned 

A DOWHILE loop O © implements traversing the display list through successive 
calls to UIS$GET_NEXT_OBJECT O. 

An object type for each display list entry is returned ©. 

Within the DOWHILE loop the subroutine DETERMINE is called ® ® which 
sorts each object identifier according to its object type ©©©©<£)©. For 
more information about object type symbols such as UIS$C_OBJECT_PLOT, see 
UIS$GET_OBJECT_ATTRIBUTES. 

Five arrays for each object type represented in the display list are declared ® 

Each object identifier is stored in one of these arrays. All counter variables have 
been initialized to the value 1 

A call to UIS$CREATE—WINDOW creates a display window and viewport and 
executes the contents of the display list in the virtual display©. 
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13.3.3.3 Calling UIS$GET-NEXT_OBJECT, UIS$GET_OBJECT_ATTRIBUTES, 
and UIS$GET_ROOT_SEGMENT 

The program WALK walks the display list and identifies each object in the display 
list. Information about each object is returned in the terminal emulation window as 
shown in Figure 13-6. 

Figure 13-6 Display List Elements 


$ run walk 
DISPLAY LIST 

ELEMENTS 

IDENTIFIER 

OBJECT TYPE 

113992 


UIS:^C_OBJECT_SEGMENT 

115328 


UIS^:C_OBJECT_ ELL IPSE 

115575 


LIIStC_OBJECT_PLOT 

115822 


liis:^c_objei::t_plot 

116069 


IJIS:?:C_OBJECT_PLOT 

116316 


LIIS^:C_OBJECT_TEXT 

116810 


LIIS:^i::^OBJECT_TEXT 

117057 


LIIS^:C:_OBJECT_LINE 

FORTRAN 

PAUSE 
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The program WALK also creates a display window and viewport containing the 
objects in the virtual display. 
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Figure 13-7 Contents of the Display List 



The footsteps of fortune are slippery 
Mirth without measure is madness 
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13.3.3.4 Program Development III 

Programming Objective 

To create a display list with nested segment, traverse upward through the segment 
path, and then search downward through a specified segment. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Create five levels of nested segments. 

4. Print the headings of the output to appear in the emulation window. 

5. Beginning at the innermost nested segment, obtain and print the parent segment 
identifier using UIS$GET_PARENT_SEGMENT. 

6. Print the headings of the output to appear in the emulation window. 

7. Choose a segment to search. 

8. Walk downward through the segment using UIS$GET_NEXT_OBJECT. 

9. Call the subroutine DETERMINE to examine and store the objects in arrays by 
object type. 

The following figure shows the structure of the display list in the program HOP. 
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If you intend to run program HOP, the subroutine DETERMINE from the preceding 
program WALK should be compiled as a separate module and linked with HOP. 

PROGRAM HOP 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

COMMON NEXT_ID1.TYPE1 

VD_ID2=UIS$CREATE_DISPLAY(-1.0,-1.0,40.0,40.0.15.0.15.0) 
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SEG_ID1=UIS$BEGIN_SEGMENT(VD_ID2) 

CALL UIS$PL0T(VD_ID2.0.0.0.12.0.5.0,12.0,7.5.17.0,10.0. 

2 12.0,15.0.12.0. 

2 12.5.7.5.15.0.0.0.7.5.5.0,0.0.0.0.2.5.7.5,0.0.12.0) 

SEG_ID2=UIS$BEGIN_SEGMENT(VD_ID2) O 

CALL UISICIRCLE(VD_ID2.0.7.5.8.0,8.0) 

SEG_ID3=UIS$BEGIN_SEGMENT(VD_ID2) 

CALL UIS$ELLIPSE(VD_ID2,0.25.0.8.0,5.0,8.0) 
SEG_ID4=UIS$BEGIN_SEGMENT(VD_ID2) 

CALL UIS$TEXT(VD_ID2.0,’MISERY LOVES COMPANY’, 

2 17.0,24.0) 

SEG_ID5=UIS$BEGIN_SEGMENT(VD_ID2) 

CALL UIS$TEXT(VD_ID2,0,’ONE SLUMBER INVITES ANOTHER’, 

2 1.0,39.0) 

CALL UIS$NEW_TEXT_LINE(VD_ID2,0) 

CALL UIS$TEXT(VD_ID2.0.’LIVING WELL IS THE BEST REVENGE’) 
CALL UIS$END_SEGMENT(VD_ID2) 

CALL UIS$END_SEGMENT(VD_ID2) 

CALL UIS$TEXT(VD_ID2,0.’SUCCESS MAKES A FOOL SEEM WISE’, 

2 1.0,19.0) 

CALL UIS$END_SEGMENT(VD_ID2) 

CALL UIS$PL0T(VD_ID2.0,20.0,25.0,35.0,25.0,35.0,35.0,20.0,35.0, 

2 20.0,25.0) 

CALL UIS$CIRCLE(VD_ID2.0,10.0.28.0.8.0) 

CALL UIS$END_SEGMENT(VD_ID2) 0 

CALL UIS$END_SEGMENT(VD_ID2) 

C HOPPING UPWARD ALONG THE SEGMENT PATH 
PRINT 45 

45 FORMAT(T2.’SEGMENT PATH’) 

PRINT 55 

55 FORMAT (Tl.’-’) 

PRINT 56 

56 FORMAT(T2.’IDENTIFIER’,T17.’LEVEL’) 

SEG_ID=SEG_ID5 © 

1=5 O 

PRINT 60.SEG_ID5.I 

DO 1=4,1,-1 0 

PARENT_ID=UIS$GET_PARENT_SEGMENT(SEG_ID) 0 

SEG_ID=PARENT_ID 
PRINT 60.PARENT_ID,I 
60 F0RMAT(T2.I10.T18,I2) 

ENDDO O 
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C SEARCHING DOWNWARD THROUGH A NESTED SEGMENT 
PRINT 65 

65 FORMAT(T2,’SEGMENT’) 

PRINT 70 

70 FORMAT (Tl.' -^-0 

PRINT 75 

75 FORMAT(T2.’IDENTIFIER’.T17,’OBJECT TYPE’) 

NEXT_ID1=UIS$GET_NEXT_0BJECT(SEG_ID2) ® 

DO WHILE(NEXT.IDl .NE. 0) ® 

TYPE1=UIS$GET_0BJECT_ATTRIBUTES(NEXT_ID1) 

CALL DETERMINE ® 

NEXT_ID1=UIS$GET_NEXT_0BJECT(NEXT.IDl.UIS$M_DL_SAME_SEGMENT) ® 

ENDDO ® ' 

WD_ID2=UIS$CREATE_WIND0W(VD_ID2,’SYS$WORKSTATION’) 

PAUSE 

END 

The program HOP contains five levels of nesting excluding the root segment. In 
order to walk the segment path, you must start at the innermost segment ©. The 
counter 1 is initialized to 5 O indicating the level of nesting from which you are 
starting. 

A DO loop is declared © O containing the call to UIS$GET__PARENT_SEGMENT 
®. The seg—id argument in UIS$GET_PARENT_SEGMENT is initialized with the 
segment identifier of segment 5 ©. The counter is decremented as each new parent 
segment identifier is returned and, in turn, is used as the seg_id argument in the 
next iteration of the loop. 

The second purpose of the program is to search a specified segment. Segments 
are searched using both parameters in UIS$GET_NEXT_OBJECT. To start at the 
beginning of a segment, initialize the seg_Jd to the value of the segment identifier 
you wish to search ®. By specifying the segment identifier of the segment you wish 
to search, UIS$GET_NEXT_OBJECT returns the identifier of the next object in the 
segment. In this example, the second segment is chosen O. 

Another DO loop is established ® ® containing a call to the subroutine 
DETERMINE. ® Note that UIS$GET_NEXT_OBJECT © now specifies both 
arguments. The search will be performed on the specified segment only. If the 
flag UIS$M_DL—SAME—SEGMENT were not specified, the search would proceed 
down to the innermost nested segment. 
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13.3.3.5 Calling UIS$GET_PARENT-SEGMENT 

Segment identifiers are returned beginning with the innermost nested segment as 
shown in Figure 13-8. 

Figure 13-8 Traversing Upward Along the Segment Path 


$ RUN HOP 

SEGMENT PATH 

IDENTIFIER 

LEVEL 

122664 

5 

121576 

4 

120488 

3 

119400 


115592 

1 
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Object identifiers within the second-level segment are displayed as shown in 
Figure 13-9. 

Figure 13-9 Searching Downward Through a Segment 


SEGMENT 

IDENTIFIER 

OBJECT TYPE 

117175 

UIS4C_0BJECT_ELLIPSE 

120488 

UIS$C_OBJECT_SEGMENT 

118904 

UIS$C_OBJECT_PLOT 

119151 

UIS$C_OBJECT_ELLIPSE 

FORTRAN PAUSE 


^ ■ 
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All the objects drawn in the virtual display are shown in Figure 13-10. 
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Figure 13-10 Contents of the Display List Drawn in the Virtual Display 
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LIVING WELL IS THE BEST REVENGE 



SUCCESS MAKES A FOOL SEEM WISE 
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13.4 More About Segments 

When you use segments in your application programs, you are creating complex 
object that can be edited or searched on a segment-by-segment basis. Segments also 
exhibit special behavior when attribute blocks are encountered. 

13.4.1 Programming Options 

Other than simply creating segments, you can manipulate them as well. 

Editing Display Lists 

You can edit a display list that contains no explicitly defined segments as well as 
display lists that contain explicitly specified segments. 

NOTE: You must use UlS$SET_INSERTION—POSITION to insert an object 
between existing objects in a display list. 

The following routines also allow you to edit the display list. 


Routine 

Function 

UIS$COPY_OBJECT 
UIS$DELETE-OBJECT 
UISSINSERT-OBJECT 
UIS$TRANSFORM_OBJECT 

Copies an object to another part of the display list 

Deletes an object from the display list 

Moves an object to another part of the display list 

Scales, rotates, and translates an object 


Modifying Attribute Blocks Within Segments 

As mentioned earlier, a segment consists of calls to graphics and text output routines, 
attribute routines, and nested segments. 

When the same attribute block is modified at two different levels of nesting, 
modifications to the innermost attribute block take precedence over any previous 
modifications in outer levels. Such attribute block modifications will influence 
graphics and text output (where applicable) at deeper levels of nesting. 

When you leave a lower-level nested segment, the original attributes of the parent 
segment are restored. Therefore, you can change attributes within a segment and not 
worry about affecting a higher-level segment. 
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13.4.2 Program Development I 

Programming Objective 
To edit a display list. 

Programming Tasks 

1. Create a virtual display. 

2. Create a series of nested segments containing calls to draw graphic objects. 

3. Create a display window and viewport. 

4. Delete an object in segment 1. 

5. Set the editing pointer to the end of segment 1. 

6. Print the headings of the output to appear in the emulation window. 

7. Add a line drawing call to the end of segment 1. 

8. Verify the contents of segment 1. 

9. Position the pointer to the end of segment 2. 

10. Add text to segment 2. 

11. Verify the contents of segment 2. 

Inserting an object in a specific location in the display list may not affect how the 
object is drawn but rather the order in which objects are drawn in the virtual display. 
The following diagram shows the structure of the display list before display editing 
in the program EDIT_LIST. 
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If you intend to run program EDIT_LIST, the subroutine DETERMINE from the 
preceding program WALK should be compiled as a separate module and linked with 
EDIT_LIST. 

PROGRAM EDIT.LIST 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

COMMON NEXT_ID1,TYPE1 

C Create a virtual display 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,50.0.50.0,15.0.15.0) 
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c Create a segment 

SEG_ID1=UIS$BEGIN_SEGMENT(VD_ID) O 

CALL UIS$CIRCLE(VD_ID.0.8.0,35.0,7.0) © 

CURR_ID1=UIS$GET_CURRENT_0BJECT(VD_ID) @ 

CALL UIS$PLOT(VD_ID,0,17.0,27.0,32.0,27.0,24.5.42.0,17.0,27.0) 
CURR_ID2=UIS$GET_CURRENT_0BJECT(VD_ID) 
c Create another segment 

SEG_ID2=UIS$BEGIN_SEGMENT(VD.ID) O 

CALL UIS$ELLIPSE(VD_ID.0,8.0.15.0.5.0.9.0) 
CURR_ID4=UIS$GET_CURRENT_0BJECT(VD_ID) 

CALL UIS$PL0T(VD_ID.0,15.0,8.0,30.0,8.0, 

2 35.0,22.0,20.0.22.0.15.0.8.0) 

CURR_ID5=UIS$GET_CURRENT_0BJECT(VD_ID) 

CALL UIS$END_SEGMENT(VD_ID) 

CALL UIS$TEXT(VD_ID,0,’The ox when weariest treads surest’, 

2 5.0,47.0) 

CURR_ID6=UIS$GET_CURRENT_0BJECT(VD_ID) 

CALL UIS$END_SEGMENT(VD_ID) 

WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$W0RKSTATI0N’) 

PAUSE 

c Delete an object from segment 1 

CALL UIS$DELETE_0BJECT(CURR_ID1) @ 

c Set the editing pointer at the end of segment 1 

CALL UIS$SET_INSERTI0N_P0SITI0N(SEG_ID1,) © 

CALL UIS$PL0T(VD_ID.0,29.0,42.0,44.0,42.0,36.5,27.0,29.0,42.0) O 

PRINT 20 

20 FORMAT(T2.’CONTENTS OF SEGMENT 1’) 

PRINT 25 

25 FORMAT(T2.’IDENTIFIER’,T14,’OBJECT’.T22.’TYPE’) 

PRINT 30 

30 FORMATC’-’) 

c Verify the contents of segment 1 

NEXT.ID1=UISSGET.NEXT.OBJECT(SEG.ID1) 

DO WHILE(NEXT.IDl .NE. 0) 

TYPE1=UIS$GET_0BJECT_ATTRIBUTES(NEXT_ID1) 

CALL DETERMINE ® 

NEXT_ID1=UIS$GET_NEXT_0BJECT(NEXT.IDl.UIS$M_DL.SAME.SEGMENT) 

ENDDO 

PAUSE 

c Set the editing pointer at the end of segment 2 

CALL UIS$SET.INSERTION.POSITION(SEG.ID2) © 

CALL UIS$TEXT(VD.ID,0.’Old foxes want no tutors’. 

2 5.0,45.0) © 
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PRINT 40 

40 FORMAT(T2.’CONTENTS OF SEGMENT 2’) 

PRINT 45 

45 FORMAT(T2.’IDENTIFIER’,T14.’OBJECT’.T22.’TYPE’) 

PRINT 50 

50 FORMATC’-’) 

c Verify the contents of segment 2 

NEXT_ID1=UIS$GET_NEXT_0BJECT(SEG_ID2) 

DO WHILE(NEXT.IDl .NE. 0) 
TYPE1=UIS$GET_0BJECT_ATTRIBUTES(NEXT_ID1) 

CALL DETERMINE ® 

NEXT_ID1=UIS$GET_NEXT_0BJECT(NEXT_ID1.UIS$M_DL_SAME_SEGMENT) 

ENDDO 

PAUSE 

END 

Two segments are created O O. The second segment is nested within the first. 

Successive calls to UIS$GET_CURRENT_OBJECT @ retrieve an object identifier for 
each object in both segments. This is useful if you need to insert an object in the 
display list later. 

A call to UIS$DELETE—OBJECT © deletes a circle © from segment 1 in the display 
list. 

The editing pointer in the display list is set at the end of segment 1 using UIS$SET_ 
INSERTION-POSITION ©. A call to UIS$PLOT is added to segment 1 O. 

A call to the subroutine DETERMINE © verifies the addition in the display list. 

The editing pointer in the display list is set at the end of segment 2 using UIS$SET— 
INSERTION—POSITION ©. The binary instruction resulting from a call to 
UIS$TEXT is added to segment 2 ®. 

A call to the subroutine DETERMINE © verifies the changes in the display list. 

The following figure shows the structure of the display list after display editing. 
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13.4.2.1 Calling UISSSET-INSERTION-POSITION 

The original objects, text, a circle, an ellipse, a triangle, and a parallelogram are 
shown in Figure 13-11. 



Display Lists and Segmentation 13-27 


Figure 13-11 Before Display List Modification 
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A triangle and a line of text are added to the virtual display. The circle is deleted 
from the virtual display as shown in Figure 13-12. 


Figure 13-12 Executing the Modified Display List 
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The contents of the segment are written to the emulation window as shown in 
Figure 13-13. 

Figure 13-13 Verifying the Contents of the Display List 


$ run edit_list 

FORTRAN PAUSE 
$ cont 

CONTENTS OF SEGMENT 1 

IDENTIFIER OBJECT TYPE 

116663 

UIStC_OBJECT_PLOT 

118888 

UIS^C_OBJECT_SEGMENT 

117404 

UIS^C_OBJECT_TEXT 

117651 

UIS$C:_OBJECT_PLOT 

FORTRAN PAUSE 

$ cont 


CONTENTS OF 

SEGMENT 2 

IDENTIFIER 

OBJECT TYPE 

116910 

UIS$C_0BJ EC T_EL LIPSE 

117157 

UIS$C_OBJECT_PLOT 

116416 

UIS$C_OBJECT_TEXT 

FORTRAN PAU 

SE 

v 
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13.4.2.2 Program Development II 

Programming Objective 

To draw text at different levels of segmentation. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Create three levels of nested segments. 

4. Modify the font character spacing attributes for each level of nesting. 

5. Draw text at each level of nesting. 
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Font names specified in the program are logical names. 

PROGRAM SEGMENT 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY;UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0.30.0,30.0,21.0,5.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’) 

CALL UIS$BEGIN_SEGMENT(VD_ID) O 

CALL UIS$SET_FONT(VD_ID.0.1.’MY_F0NT_6’) Q 

CALL UIS$SET_CHAR_SPACING(VD_ID.1.1,0.0,1.0) © 

CALL UIS$TEXT(VD_ID,1,’The resolved mind has no cares’,0.0,30.0) i 

CALL UIS$BEGIN_SEGMENT(VD_ID) © 

CALL UIS$SET_F0NT(VD_ID.1.1.’MY_F0NT_13’) © 

CALL UIS$NEW_TEXT_LINE(VD_ID.1) 

CALL UIS$TEXT(VD_ID,1,’The camel never sees its own hump’) © 

CALL UIS$BEGIN_SEGMENT(VD_ID) © 

CALL UIS$SET_FONT(VD_ID.1.1.’MY_F0NT_7’) © 

CALL UIS$NEW_TEXT_LINE(VD_ID,1) 

CALL UIS$TEXT(VD_ID.l.’First things first’) 

CALL UIS$END_SEGMENT(VD_ID) © 

PAUSE 

CALL UIS$SET_CHAR_SPACING(VD_ID,1.1.0.0,0.0) © 

CALL UIS$NEW_TEXT_LINE(VD_ID,1) 

CALL UIS$TEXT(VD_ID,1,’A new broom sweeps clean’) ® 

CALL UIS$END_SEGMENT(VD_ID) ® 

CALL UIS$NEW_TEXT_LINE(VD.ID,1,) 

CALL UIS$TEXT(VD_ID,1.’No sun without a shadow’) ® 

CALL UIS$END_SEGMENT(VD_ID) © 

PAUSE 

END 

The first call to UIS$BEGIN_SEGMENT O and the final call to UIS$END_ 

SEGMENT ® establish the limits of the first-level segment. Within this segment 
there are two calls to UIS$TEXT O ©. The first call to UIS$TEXT establishes the 
current position for all text output created at the first level. 

An attribute routine UIS$SET_FONT is called © which modifies the font attribute. 

The font MY_FONT_6 is now the current font for all text output in the first-level 
segment. Text created at the first level will be drawn using MY_JFONT_6. 
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The calls to UIS$BEGIN_SEGMENT and U1S$END_SEGMENT 0 ® establish the 
limits of the second-level segment nested within the first-level segment. The first 
call to UIS$SET_JFONT © in the second-level segment references the same output 
attribute block number specified in the attribute routine call in the first-level segment 
©. The modifications to attribute block 1 at the second level take precedence over 
any previous modifications of attribute block 1 at outer levels. 

The second-level segment further modifies the font attribute ©. The font MY_ 
FONT_13 is now the current font for all text output in this second-level segment. 
The first call to UIS$TEXT within the second-level segment © establishes the current 
position for text output drawn at the second level. Calls to UIS$TEXT within this 
segment reference the same attribute block 1. 

Once again, calls to UIS$BEG1N-SEGMENT and UIS$END_SEGMENT © © 
establish the limits of the third level of segmentation nested within the second level. 
The font MY—FONT_7 is now the current font for all text output in this segment ©. 

The line spacing component of the character spacing attribute was modified twice 
® ®. The first call to UIS$SET—CHAR—SPACING was made to increase the line 
spacing by a factor of 1. As the program executes, the second text drawing routine 
call in levels 1 and 2 © © require room to avoid overstriking existing lines. 

13.4.2.3 Calling UIS$BEGIN_SEGMENT and UIS$END_SEGMENT 

As the program SEGMENT executes each instruction sequentially, a text string is 
drawn in the virtual display at the first, second, and third levels of segmentation as 
shown in Figure 13-14. Please note the font used in text creation. 

Figure 13-14 Text Output During Execution 


llffhe resolved mind has no cures 


The camel never sees its own hump 
First things first 


Text strings are then created in the reverse order of segmentation—second level and 
then first level. Please note the font used and the order of text string creation as 
shown in Figure 13-15 as compared to the statements in the source program. 
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Figure 13-15 Final Text Output 



The resolved mind has no cares 
No sun without a shadow 


Tlie camel never sees its own liump 

A new broom sweeps clean 
First things first 
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Chapter 14 

Geometric and Attribute Transformations 


14.1 Overview 

Transformations alter the appearance of graphic objects and text. In Part I, 
viewing transformations and their possibly distorting effects on graphic objects 
were discussed. Already in Part II you have seen the effects of world coordinate 
transformations when you modify the world coordinate space and then redraw 
graphic objects in the new space. This chapter describes the following two types of 
transformations; 

• Two-dimensional geometric transformations 

• Attribute transformations 


14.2 Geometric Transformations 

A two-dimensional geometric transformation of a graphic object involves changing 
the graphic object's angular orientation or its shape within the virtual display. The 
coordinate system is not modified. Graphic objects are geometrically transformed 
using the following methods: scaling, translation, and rotation. 

14.2.1 Translating Graphic Objects 

Translating a graphic object involves moving the object to another part of the 
coordinate space without altering its physical orientation with respect to the x and 
y axes. For example, a side of a triangle that was originally parallel to the y axis 
remains parallel to that axis even if the object is moved to another quadrant in the 
coordinate space. 



14-2 Geometric and Attribute Transformations 


Figure 14-1 Translating a Graphic Object 
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14.2.2 Scaling Graphic Objects 

Typically, scaling involves stretching or shrinking a graphic object. Scaling a graphic 
object can occur in two ways: (1) simple scaling of the graphic object in the virtual 
display or (2) complex scaling. 

Simple Scaling of Graphic Objects 

Simple scaling of a graphic object involves executing a single transformation. The 
position of the newly scaled graphic object in the virtual display is always different 
from its original position with one exception. If the object's center point is at the 
origin, the object will not move when scaled. 
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Figure 14-2 Simple Scaling 
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Complex Scaling of Graphic Objects 

Complex scaling of graphic objects ensures that the newly scaled object maintains 
its previous position in the virtual display. The center of the object is first translated 
to the origin of the coordinate system, scaled, and finally translated to its original 
position. 


Figure 14-3 Complex Scaling 
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14.2.2.1 Uniformly Scaled Graphic Objects 

For example, a photographic enlargement of a snapshot to poster size renders an 
object whose physical dimensions are proportional to the snapshot. In such a case, 
the scaling factor of the width of the object, Sx, equals the scaling factor of the height 
of the object, Sy. 


Figure 14-4 


Uniformly Scaling a Graphic Object 
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14.2.2.2 Differentially Scaled Graphic Objects 

Scaling need not be performed uniformly. For example, the height of an object may 
be increased while its width remains constant where Sx does not equal Sy. The object 
is differentially scaled as shown in Figure 14-5. 

Figure 14-5 Differentially Scaling a Graphic Object 
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14.2.3 Rotating Graphic Objects 

Generally speaking, rotation changes an object's angular orientation in the virtual 
display. All rotations occur about the origin of the coordinate system. Positive 
rotation is a counterclockwise movement. 

Simple Rotation of Graphic Objects 

Simple rotation of graphic objects involves executing a single transformation—no 
translation. With simple rotation, the object appears to revolve about the origin. 
Figure 14-6 shows rectangle rotating about the origin. 
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Figure 14-6 Simple Rotation of a Graphic Object 
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Complex Rotation of Graphic Objects 

Complex rotation can occur when the reference or pivotal point is the center 
of the object. Complex rotation of the graphic object is accomplished by first 
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translating the object to the origin so that the origin and reference point share the 
same coordinate values—(0.0,0.0). The object is rotated and translated to its original 
position in the virtual display. Figure 14-7 illustrates complex rotation of a rectangle. 

14.2.4 Programming Options 

You can perform geometric transformations of two types. 

TwO'Dimensional Geometric Transformation—COPY 

You may execute a geometric transformation where the graphic object is copied using 
UIS$COPY_OBJECT. The original object remains unchanged. 

Two-Dimensional Geometric Transformations—MOVE 

You may execute a geometric transformation where the graphic object is transformed 
in the virtual display using UlS$TRANSFORM_OBJECT. The original object is 
modified. 

14.2.5 Program Development I 

Programming Objective 

To rotate a graphic object in a positive counterclockwise 45 degrees about its center. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Create a graphic object and obtain its identifier. 

4. Declare and load a two-dimensional array with translation values. 

5. Execute translation. 

6. Load array with rotation values. 

7. Execute rotation. 

8. Load array with translation values. 

9. Execute the translation where the original object is erased and redraw the object 
in its original position in the coordinate system. 



Geometric and Attribute Transformations 14-11 


PROGRAM GEO_TRANSFORM_ROT 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL*4 MATRIX(2.3) O 

VD_ID=UIS$CREATE_DISPLAY(-20.0.-20.0.20.0.20.0,10.0.10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’) 

CALL UIS$PLOT(VD_ID.0.0.0.20.0.0.0,-20.0) © 

CALL UIS$PLOT(VD_ID.0,-20.0.0.0.20.0.0.0) © 

CALL UIS$PLOT(VD_ID.0.5.0.5.0,15.0.5.0,15.0,10.0.5.0.10.0, 
2 5.0,5.0) O 

CURRENT_ID=UIS$GET_CURRENT_OBJECT(VD_ID) © 
OBJ_ID=CURRENT_ID 

PAUSE 

MATRIX(1.1)=1.0 © 

MATRIX(2.1)=0.0 
MATRIX(1.2)=0.0 
MATRIX(2.2)=1.0 
MATRIX(1.3)=-10.0 
MATRIX(2,3)=-7.5 

CALL UIS$TRANSF0RM_0BJECT(OBJ_ID.MATRIX) © 

PAUSE 

MATRIX(1,1)=C0SD(45.0) 

MATRIX(2.1)=-SIND(45.0) 

MATRIX(1.2)=SIND(45.0) 

MATRIX(2,2)=C0SD(45.0) 

MATRIX(1,3)=0.0 
MATRIX(2,3)=0.0 
CALL UIS$TRANSFORM_OBJECT(OBJ 

PAUSE 

MATRIX(1.1)=1.0 © 

MATRIX(2.1)=0.0 
MATRIX(1,2)=0.0 
MATRIX(2.2)=1.0 
MATRIX(1.3)=10.0 
MATRIX(2.3)=7.5 

CALL UIS$TRANSFORM_OBJECT(OBJ_ID.MATRIX) © 

PAUSE 
END 

A two-dimensional array is declared O. 


© 


_ID.MATRIX) © 
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The X and y axes are drawn O O. 

A rectangle is drawn using UIS$PLOT O. Call UIS$GET_CURRENT_OBJECT to 
save its object identifier 0. The object identifier is used as an argument to the 
transformation routine. 

The rectangle will be rotated about its center. 

The VAX FORTRAN intrinsic functions SIND and COSD accept degrees as arguments 

0 . 

The matrix is loaded with values three times 0 0 0 to translate, rotate the rectangle 
about its center, and then translate it to its original position in the virtual display. 

Each transformation is performed as the original object is erased and redrawn in its 
new orientation. The rectangle is redrawn with each call to UIS$TRANSFORM_ 
OBJECT 0 0 0. 

14.2.6 Calling UIS$TRANSFORMATION_OBJECT 

The program GEO_TRANSFORM__ROT translates, rotates, and translates a rectangle 
using UIS$TRANSFORM_OBJECT. With each transformation, the rectangle's 
previous position in the virtual display is erased as shown in Figure 14-7. 

14.2.7 Program Development II 

Programming Objective 

To rotate a copy of the graphic object 45 degrees about its center and place the 
rotated copy in another quadrant. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and viewport. 

3. Declare and load a two-dimensional array with translation values. 

4. Execute the COPY operation and the translation. 

5. Load the array with rotation values. 

6. Execute rotation. 

7. Load array with translation values. 

8. Execute translation. 
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Figure 14-7 Complex Rotation of a Rectangle 
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PROGRAM COPY.OBJECT 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY;UISUSRDEF’ 

REAL+4 MATRIX(2.3) 

VD_ID=UIS$CREATE_DISPLAY(-20.0,-20.0.20.0.20.0.10.0,10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’) 

CALL UIS$PLOT(VD_ID.0.0.0,20.0,0.0,-20.0) 

CALL UIS$PLOT(VD.ID.0,-20.0,0.0.20.0,0.0) 

CALL UIS$PLOT(VD_ID,0.5.0.5.0,15.0.5.0,10.0,10.0.5.0,5.0) 

CURRENT_ID=UIS$GET_CURRENT_OBJECT(VD_ID) 

OBJ_ID=CURRENT_ID 

PAUSE 

MATRIX(1,1)=1.0 
MATRIX(2,1)=0.0 
MATRIX(1,2)=0.0 
MATRIX(2,2)=1.0 
MATRIX(1,3)=-10.0 
MATRIX(2.3)=-7.5 

COPY_ID=UIS$COPY_OBJECT(OBJ_ID,MATRIX) O 
PAUSE 

0BJ_ID=C0PY_ID © 

MATRIX(1.1)=C0SD(45.0) @ 

MATRIX(2,1)=-SIND(45.0) 

MATRIX(1,2)=SIND(45.0) 

MATRIX(2.2)=C0SD(45.0) 

MATRIX(1,3)=0.0 
MATRIX(2.3)=0.0 

CALL UIS$TRANSFORM_OBJECT(OBJ_ID,MATRIX) O 
PAUSE 

MATRIX(1.1)=1.0 
MATRIX(2.1)=0.0 
MATRIX(1.2)=0.0 
MATRIX(2.2)=1.0 

MATRIX(1.3)=-10.0 @ 

MATRIX(2.3)=7.5 

CALL UIS$TRANSFORM_OBJECT(OBJ_ID,MATRIX) 

PAUSE 

END 
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This program is almost identical to the previous program GEO_TRANSFORM__ROT 
with a few important differences. 

The first transformation is executed O. The triangle is copied and translated to the 
origin of the coordinate space. The coordinates of the center of the triangle match 
those of the origin. The original triangle in the first quadrant remains unchanged. 

The identifier of the transformed object copy—id is assigned to the obj—id O. It will 
be used as an argument in the next transformation. 

The VAX FORTRAN intrinsic functions SIND and COSD accepts degrees as 
arguments 0 . 

A call to UIS$TRANSFORM_OBJECT rotates the translated triangle 45 degrees O. 
The original object is erased and redrawn in its new orientation. 

The final translation of the triangle places it in the second quadrant at a 45-degree 
angle to the original triangle 0 . 

14.2.8 Calling UIS$COPY_OBJECT 

The triangle is transformed similarly to the rectangle in the previous example. 
However, the first transformation copies the triangle. Figure 14-8 shows that the 
triangle still remains in the virtual display. However, the rotated copy of the triangle 
is translated to the second quadrant. 
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Figure 14-8 Complex Rotation of a Triangle 
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14.3 Attribute Transformations 

Attribute transformations involve modifying graphic objects and text without having 
to know the attribute block of the original graphics or text objects. 

14.3.1 Programming Options 

Attribute Transformations 

Ordinarily, when you modify the appearance of an existing graphic object, you must 
perform the follow procedure: 

1. Obtain the object identifier. 

2. Call UIS$DELETE_OBJECT with the object identifier. 

3. Redraw the graphic object or text using the modified attribute block. 

At the very least, you must use two steps—erase the virtual display using 
UIS$ERASE and redraw the object with a modified attribute block. 

A call to UIS$COPY_OBJECT or UIS$TRANSFORM_OBJECT specifying the atb 
argument and omitting the matrix argument lets you modify the attributes of graphic 
objects and text in a single call. 

To disable attribute transformations, omit the atb argument in UlS$COPY_OBJECT 
or UIS$TRANSFORM_OBJECT. 

14.3.2 Program Development 

Programming Objective 

To modify the fill pattern of a circle as a transformation. 

Programming Tasks 

1. Create a virtual display. 

2. Create a display window and a display viewport. 

3. Draw a circle using default attributes. 

4. Obtain its object identifier. 
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5. Modify the fill pattern attribute. 

6. Transform the circle's attributes and draw the modified circle. 

PROGRAM ATTR.TRANS 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYSSLIBRARY;UISUSRDEF’ 

VD_ID=UIS$CREATE_DISPLAY(-10.5.-10.5,10.5,10.5.10.0.10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’) 

CALL UIS$CIRCLE(VD_ID.0,0.0.0.0,10.0) 
CURRENT_ID=UIS$GET_CURRENT_OBJECT(VD_ID) 

OBJ_ID=CURRENT_ID 

CALL UIS$SET_F0NT(VD_ID,0,1,’UIS$FILL_PATTERNS’) O 
CALL UIS$SET_FILL_PATTERN(VD_ID,1.1.PATT$C_D0WNDIAG1_7) © 

PAUSE 

CALL UIS$TRANSFORM_OBJECT(OBJ_ID.,1) 0 

PAUSE 

END 

A matrix is not declared in this program. Therefore, the position of any objects 
drawn will be the same. 

The fill pattern attribute is modified O ©. 

The object identifier of the original circle and attribute block number of the newly 
modified attribute block are arguments in the transformation ©. 


14.3.3 Requesting Attribute Transformations 

Because no matrix was specified in the transformation, the resulting transformation 
will not cause objects to change their positions within the virtual display. The 
original circle is erased and the modified circle is placed in its position as shown in 
Figure 14-9. 
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If the call to UIS$TRANSFORM-OBJECT were instead a call to UIS$COPY_OBJECT, 
the original circle would remain visible in the virtual display. The modified circle 
would still be placed in the same position. 

Figure 14-10 Modifying Attributes with a Copy 
















Chapter 15 

Metafiles and Private Data 


15.1 Overview 

Many of your applications produce displays that you might wish to use again. In 
order to reexecute these displays you must first store them in a UIS metafile. We 
will describe the structure of a metafile and the contents of the binary encoded 
instructions in more detail. 

An additional feature allows you to associate data with your graphics objects. You 
can specify a particular graphic object or group of objects within the display to be 
associated with the user-defined data. This chapter discusses metafiles and private 
data in the following topics; 

• Extracting data from a display list 

• Interpreting the user buffer 

• Creating a UIS metafile 

• Creating private data 

Hardcopy UIS (HCUIS) translates UIS pictures to other formats. See the MicroVMS 
Workstation Guide to Printing Graphics for more information about HCUIS. 


15.2 Display Lists and UIS Metafiles 

Generating graphic objects on the display screen is the purpose of your application 
programs. As a programmer, you are also concerned with program modularity and 
efficiency. With each new object drawn in the virtual display, a new entry is added 
to the display list. Preserving the contents of a display list as generically encoded 
binary instructions for use across many applications is highly desirable. Graphics 
output and attribute modifications can then be extracted from display lists and stored 
in user-defined buffers as metafile components and in files as metafiles. 



15-2 Metafiles and Private Data 


15.2.1 Generic Encoding of Graphics and Attribute Routines 

As mentioned earlier, whenever an object is drawn in the virtual display or an 
attribute is modified, a binary encoded instruction is added to the display list of the 
specified virtual display. Entries in the display list are variable length instructions 
and are encoded as shown in Figure 15-1. 

Figure 15-1 Binary Encoded Instruction 


Op code Length 

16 bits 16 bits 


Arguments 


ZK-5472-86 

If the length of the binary encoded instruction is greater than 32,767 bytes, the length 
field should be set equal to U1S$C_LENGTH_D1FF and the extra length should be 
set equal to the total number of bytes in the instruction. Figure 15-2 describes the 
format of a display list entry, if the length field is greater than 32,767 bytes. 

Figure 15-2 Extended Binary Encoded Instruction 


Op code 

16 bits 

■11 

Extra Length 

32 bits 

Arguments 
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15.2.1.1 Normalized Coordinates 

The coordinate system used within display lists and when creating generically 
encoded streams is normalized coordinates. Normalized coordinates are floating point 
numbers in the range (0.0,0.0) to (max_nc_x,max_nc_y) where (0.0,0.0) refers to 
lower-left comer of the virtual display and (max__nc_x,max_nc_y) refers to the 
upper-right corner. 

Normalized coordinates are used within UIS as a means of deferring the actual 
mapping of an application's world coordinates to device-specific coordinates until the 
actual output device is known. For example, the device coordinates of a printer may 
be very different from the device coordinates of a raster display. 
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15.2.1.2 Interpreting the User Buffer 

When UIS routine calls are executed, binary encoded instructions are added to the 
display list. When you extract the contents of a display list and store them in a 
buffer, you have created metafile components—header data, an encoded stream of 
binary instructions, and trailer data. Each metafile component consists of binary 
encoded instructions. If you write the contents of the buffer to a file, you have 
created a UIS metafile. A UIS metafile is a generically encoded binary stream, that 
is, all three components exist within a single file and the file is executable on any 
VAXstation system. The contents of the buffer and metafile contains values that 
describe the extracted objects. If reexecuted, these encoded instructions cause UIS 
to recreate the objects drawn in the virtual display. Note that monochrome systems 
cannot duplicate the color of extracted objects created on color systems. 

It is possible to write your own binary encoded instructions and metafiles. First, you 
must understand how to interpret the contents of the user-defined buffer containing 
the extracted data. 

Opcodes 

The portion of the binary encoded instruction that specifies the action that the 
instruction performs is the opcode. Table 15-1 lists the generic encoding symbols 
and the corresponding opcodes of binary encoded instructions. 

Table 15-1 Generic Encoding Symbols and Opcodes 


Generic Encoding Symbol Opcode 

Attribute 

GER$C_SET_WRITING_MODE 1 

GER$C_SET_WRITING-INDEX 2 

GER$C_SET_BACKGROUND_INDEX 3 

GER$C_SET_CHAR_SPACING 4 

GER$C_SET_CHAR-SLANT 5 

GER$C-SET-TEXT-SLOPE 6 

GER$C-SET_TEXT-PATH 7 

GER$C-SET-TEXT-FORMATTING 11 

GER$C-SET-CHAR-ROTATION 12 

GER$C-SET-TEXT-MARGINS 13 

GER$C-SET-LINE-WIDTH 14 

GER$C-SET-LINE-STYLE 15 

GER$C-SET-FONT 17 

GER$C-SET_ARC-TYPE 26 
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Table 15-1 (Cent.) Generic Encoding Symbols and Opcodes 


Generic Encoding Symbol 

Opcode 

Attribute 

GER$C_SET_FILL _PATTERN 

37 

GER$C_SET_CLIP 

38 

GER$C_SET_CHAR_ENCODING 

39 

GER$C_SET_CHAR_SIZE 

42 


Graphics and Text 


GER$C_TEXT 

19 

GER$C_SET_POSITION 

21 

GER$C_PLOT 

23 

GER$C_ELLIPSE 

25 

GER$C_IMAGE 

29 

GER$C_ALIGN-POSITION 

33 

GER$C_LINE 

52 

Application-specific Private Data 

GER$C_PRIVATE 

30 


Display List 


GER$C_BEGIN^ 

31 

GER$C_END^ 

32 

GER$C_BEGIN-DISPLAY 

34 

GER$C-END-DISPLAY^ 

35 

GER$C-VERSION 

36 

GER$C-IDENTIFICATION 

43 

GER$C-DATE 

44 

GER$C-NOP^ 

45 

GER$C-PRIVATE -ECO 

49 

GER$C_DISPLAY-EXTENTS 

51 

Color 

GER$C-SET-COLORS 

47 
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Table 15-1 (Cont.) Generic Encoding Symbols and Opcodes 


Generic Encoding Symbol 

Opcode 

Color 

GER$C_SET_INTENSITIES 

48 

GER$C_CREATE_COLOR_MAP 

50 


Arguments 

Figure 15-3 illustrates the format of an argument within a binary instruction that 
changes attribute settings. 

Figure 15-3 Format of Attribute-Related Argument 


Op code 


lATB 

16 bits 


16 bits 


OATB 
16 bits 


Arguments 
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Figure 15-4 illustrates the format of an argument within a binary encoded instruction 
that produces graphics or text. 

Figure 15-4 Format of Graphics- and Text-Related Argument 


Op code 

16 bits 


ATB 

16 bits 

Arguments 
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Table 15-2 lists the possible arguments that can appear in a binary encoded 
instruction. 
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Table 15-2 Arguments of Binary Encoded Instructions 


Opcode 

Argument 

Data Type 

Description 

Attributes^ 


iatb 

word 

Input attribute block 
for set operations 


oatb 

word 

Output attribute block 
for set operations 

GER$C_SET_ARC_ 

TYPE 

arc_type 

word 

arc type 

GER$C_SET_ 

BACKGROUND- 

INDEX 

background-index 

word 

Background index 

GER$C_SET_ 

char—encoding—type 

word 

Character encoding 

CHAR_ENCODING 



type 

GER$C_SET_ 

char—size—flags 

word 

Scaling flags 

CHAR_SIZE 

char—size—enable 

bitfield mask 

Font ideal size for x 


char—size—def—x 

bitfield mask 

Font ideal size for y 


char—size—def—y 

bitfield mask 

Widest char 


char—size—def—char 

bitfield mask 



char—size—example 

word 

Example character 


char—size—width 

F—floating 

Character width 


char—size—height 

F—floating 

Character height 

GER$C_SET_ 

CHAR_SLANT 

char—slant —angle 

F—floating 

Character slant angle 

GER$C_SET_ 

char—space—dx 

F—floating 

Delta X spacing 

CHAR_SPACING 

char—space—dy 

F—floating 

Delta y spacing 

GER$C_SET_ 

char—rotation —angle 

F—floating 

Character rotation 

CHAR_ROTATION 



angle 

GER$C_SET_CLIP 

clip—flags 

word 

Clipping rectangle 


clip—xl 

F—floating 



clip—yl 

F—floating 



clip—x2 

F—floating 



clip—y2 

F—floating 



^All attribute-related encoding items start with input attribute block (lATB) and output attribute block 
(OATB) numbers and then contain attribute specific information. 


^Arguments whose data type is word, longword, or character use the prefix GER$W_, GER$F_, or 
GER$G, respectively, EXCEPT GER$L_LINE_STYLE and GER$L_IMAGE_SIZE. For example, 
GER$W_IATB, GER$F_CHAR_SIZE_WIDTH, or GER$G_FONT_ID_STRlNG. 
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Table 15-2 (Cont.) Arguments of Binary Encoded Instructions 


Opcode 

Argument 

Data Type 

Description 

Attributes^ 




GER$C_SET_ 

COLORS 

color—count 

word 

Number of indices 


color-index 

word 

First index 


color—values 

longword array 

R, G, and B vectors 

GER$C_SET_FILL_ 

PATTERN 

fill—flags 

word 

Flags 


fill—index 

word 

Index 

GER$C_SET_FONT 

font—id—length 

word 

Font name length 


font—id—string 

character 

Font name string 

GER$C-SET- 

INTENSITIES 

intensity—count 

word 

Number of indices 


intensity—index 

word 

First index 


intensity—values 

longword array 

I vector 

GER$C_SET_LINE_ 

STYLE 

line—style 

longword 

3 2-bit bitvector 

GER$C_SET_LINE_ 

WIDTH 

line—width—nc 

F—floating 

Normalized coordinates 


line—width—dc 

F—floating 

Pixel coordinates 


line—width—mode 

word 

Width mode 

GER$C_SET_TEXT_ 

FORMATTING 

text—format—mode 

word 

Text formatting mode 

GER$C_SET_TEXT_ 

MARGINS 

text—margin—X 

text—margin—y 

F—floating 

F—floating 

Starting position 


text —margin —distance 

F—floating 

Ending position 

GER$C_SET_TEXT_ 

PATH 

text—path—major 

word 

Major path code 


text—path—minor 

word 

Minor path code 

GER$C_SET_TEXT_ 

SLOPE 

text—slope—angle 

F—floating 

Angle of text slope 


^All attribute-related encoding items start with input attribute block (lATB) and output attribute block 
(OATB) numbers and then contain attribute specific information. 

^Arguments whose data type is word, longword, or character use the prefix GER$W_, GER$E_, or 
GER$G, respectively, EXCEPT GER$L_LINE_STYLE and GER$L_IMAGE_SIZE. For example, 
GER$W_1ATB, GER$F_CHAR-SIZE-WIDTH, or GER$G-FONT-ID-STRING. 
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Table 15-2 (Cont.) Arguments of Binary Encoded Instructions 


Opcode 

Argument^ 

Data Type 

Description 

Attributes^ 

GER$C_SET_ 

WRITING-MODE 

writing—mode 

word 

Writing mode 

GER$C_SET_ 

WRITING-INDEX 

writing—index 

word 

Writing index 

5 

Graphics and Text 


output—atb 

word 

ATB for graphics and 
text operations 

GER$C_ELLIPSE 

ellipse—X 

F—floating 

Center point 


ellipse—y 

F—floating 



ellipse—width 

F—floating 

Radius width and 
height 


ellipse—height 

F—floating 



ellipse—start —deg 

F—floating 

Starting and ending 
degrees 


ellipse—end—deg 

F—floating 


GER$C_IMAGE 

image—xl 

F—floating 

Lower-left corner of 
raster image 


image—yl 

F—floating 



image—x2 

F—floating 

Upper-right corner of 
raster image 


image—y 2 

F—floating 



image—width 

word 

Image width in pixels 


image—height 

word 

Image height in pixels 


image—bpp 

word 

Bits per pixel 


image—size 

longword 

Number of bytes in 
image 


^All attribute-related encoding items start with input attribute block (lATB) and output attribute block 
(OATB) numbers and then contain attribute specific information. 

^All output-related encoding items start with an attribute block (ATB) number and then followed by 
graphics and text output information. 

^Arguments whose data type is word, longword, or character use the prefix GER$W_, GER$F_, or 
GER$G, respectively, EXCEPT GER$L_LINE_STYLE and GER$L-IMAGE_SIZE. For example, 
GER$W_IATB, GER$F_CHAR_SIZE_WIDTH, or GER$G_FONT_ID_STRING. 
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Table 15-2 (Cont.) Arguments of Binary Encoded Instructions 


Opcode 

Argument^ 

Data Type 

Description 

Graphics and Text^ 


image_data 

byte array 

Place to store actual 
data 

GER$C_PLOT 

plot—count 

word 

Number of points 


plot—data 

longword array 

Points 

GER$C_TEXT 

text—encoding 

word 

8- or 16-bit encoding 


text—length 

word 

Text length in bytes 


text—data 

character 

Text string 

GER$C_LINE 

line—count 

word 

Number of points 


line—data 

longword array 

Points 

Color Map 

GER$C_CREATE_ 

COLOR-MAP 

color—map—attributes 
color—map—resident 
color—map—no—bind 
color—map—share 
color—map—system 

longword 
bitfield mask 
bitfield mask 
bitfield mask 
bitfield mask 

Color map attributes 


color—map—name—size 

word 



color—map—size 

word 



color—map—name 

character 

Virtual color map name 

Private Data 

GER$C_PRIVATE 

private—facnum 

word 

Facility number 


private—length 

word 

Length of data 


private—data 

byte array 

Data 

Metafile 

GER$C_VERSION 

version—major 

word 

Encoding version 
number 


^All output-related encoding items start with an attribute block (ATB) number and then followed by 
graphics and text output information. 

^Arguments whose data type is word, longword, or character use the prefix GER$W_, GER$F_, or 
GER$G, respectively, EXCEPT GER$L_L1NE_STYLE and GER$L_1MAGE_S1ZE. For example, 
GER$W_1ATB, GER$F_CHAR_S1ZE_W1DTH, or GER$G_FONT_lD_STRING. 
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Table 15-2 (Cont.) Arguments of Binary Encoded Instructions 


Opcode 

Argument^ 

Data Type 

Description 

Metafile 


version—minor 

word 



version _eco 

word 


GER$C_ 

IDENTIFICATION 

identification —length 
identification —string 

word 

character 


GER$C_DATE 

date—length 
date—string 

word 

character 

File creation date 

GER$C_PRIVATE_ 

ECO 

private—eco—facnum 

word 



private—eco—major 

word 



private—eco—minor 

word 



private—eco—eco 

word 



Miscellaneous 


GER$C-DISPLAY- 

EXTENTS 

extent—minx 

F—floating 

Extent rectangle 


extent—miny 

F—floating 



extent—maxx 

F—floating 



extent—maxy 

F—floating 


GER$C-SET- 

POSITION 

text—pos—X 

F—floating 

Text position 


text—pos—y 

F—floating 


GER$C_ALIGN- 

POSITION 

align—pos—atb 

word 

Attribute block 


align—pos—x 

E—floating 

Position 


align—pos—y 

F—floating 


GER$C-BEGIN_ 

display—wc—minx 

f—floating 

Dimensions of virtual 

DISPLAY 

display—wc—miny 

f—floating 

display 


display—WC—maxx 

f—floating 



display—WC—maxy 

f—floating 



display—width 

f—floating 



^Arguments whose data type is word, longword, or character use the prefix GER$W_, GER$F_, or 
GER$G, respectively, EXCEPT GER$L_LINE_STYLE and GER$L—IMAGE_SIZE. For example, 
GER$W_IATB, GER$F_CHAR_SIZE_WIDTH, or GER$G_FONT_ID_STRING. 
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Table 15-2 (Cont.) Arguments of Binary Encoded Instructions 


Opcode 

Argument 

Data Type 

Description 

Miscellaneous 

GER$C_END_ 

DISPLAY 

display-height 

No arguments 

f—floating 



^Arguments whose data type is word, longword, or character use the prefix GER$W_, GER$F_, or 
GER$G, respectively, EXCEPT GER$L_LINE_STYLE and GER$L_IMAGE_SIZE. For example, 
GER$W_IATB, GER$F_CHAR_SIZE-WIDTH, or GER$G_FONT_ID_STRING. 


15.2.2 Creating UlS Metafiles 

UIS metafiles are encoded binary instructions which when extracted from a display 
list with UIS$EXTRACT_OBJECT or UIS$EXTRACT_REGION are generically encoded. 
UIS metafiles consist of the following parts: (1) header information, (2) generically 
encoded binary instructions, and (3) a trailer. The header and trailer are special 
binary instructions that indicate the beginning and end of a UIS metafile. The generic 
encoding of UIS metafiles allows you to store the extracted contents of the display list 
in a buffer or file. Table 15-3 lists the parts of a UIS metafile. 


Table 15-3 Structure of UIS Metafiles 


Generic Encoding Symbol 

Function 

Header Information 


GER$C_VERSION 

Level of generic encoding syntax. The version always 
appears first. 

GER$C_IDENTIFICATION 

User-specified optional identification string. 

GER$C_DATE 

Optional and user-specified. 

GER$C_PRIVATE_EC0^’2 

Optional and user-specified. 

GER$C_CREATE-COLOR-MAP 

Used by UIS$EXECUTE-DISPLAY. 

GER$C-SET-COLORS 

Used by UIS$EXECUTE-DISPLAY. 

GER$C-BEGIN-DISPLAY 

Dimensions of the virtual display to be created by 
UIS$EXECUTE_DISPLAY. 


^Engineering Change Order 


^See Table 15-1 for the generic symbols in each of these categories of binary encoded instructions. 
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Table 15-3 (Cont.) Structure of UIS Metafiles 


Generic Encoding Symbol 

Function 

-*- 

Encoded Binary Instructions 

GER$C_DISPLAY_EXTENTS^ 

Bounds of an extent rectangle used in 
UIS$EXTRACT_REG10N. 

Segment 

Express the hierarchical structure within a display list 
and identify the attributes associated with a segment. 

Attribute 

Allow the modification of any attribute in any attribute 
block. A generic encoding opcode exists for each 
attribute. 

Graphics and text 

Contain the data necessary to draw graphic objects. 

Application-specific 

Associate data with a user-specified facility. 

Trailer 

GER$C_END_DISPLAY 

Ends the UIS metafile. 


^See Table 15-1 for the generic symbols in each of these categories of binary encoded instructions. 
^Generated by U1S$EXTRACT_REG10N only 


15.2.3 Structure of a UIS Metafile 

A UIS metafile consists of three parts—header information, binary instructions, and 
trailer information. Figure 15-5 illustrates the structure of a UIS metafile containing a 
single extracted graphic object. Note that attribute modification instructions precede 
the object and private data instructions follow it. Also, if the extracted object lay 
previously within a segment, segmentation instructions must surround it in the 
metafile. 
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Figure 15-5 Structure of UIS Metafile 


Header 

Information 


Beginning 

Segmentation 

Instruction 


Attribute 

Modification 

Instructions 


Extracted 
Graphic Object 


Private Data 


Ending Segmentation 
Instruction 


Trailer 

Information 


GER$C_VERSION 

Length 

Arguments 

GER$C_IDENTIFICATION 

Length 

Arguments 

GER$C_DATE 

Length 

Arguments 

GER$C_BEGIN_DISPLAY 

Length 

Arguments 

GER$C_BEGIN 

Length 

No arguments 

GER$C_SET_FONT 

Length 

lATB 

OATB 

Arguments 

GER$C_SET_FILL-PATTERN 

Length 

lATB 

OATB 

Arguments 

GER$C_ELLIPSE 

Length 

ATB 

Arguments 

GER$C_PRIVATE 

Length 

Arguments 

GER$C_PRIVATE 

Length 

Arguments 

GER$C_END 

Length 

No Arguments 

GER$C_END_DISPLAY 

Length 

No arguments 


ZK 5476 86 


Private data is discussed later in this chapter. 
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15.2.4 Programming Options 

The ability to create UIS metafiles allows you to save display screen output in files 
for reexecution at a later time. 

Creating UIS Metafiles 

You can extract an object or the contents of a region within a virtual display using 
UIS$EXTRACT_HEADER, UlS$EXTRACT_OBJECT or UIS$EXTRACT_REGION, 
UIS$EXTRACT_TRAILER and store the data in a buffer or file as a metafile using the 
following procedure: 

1. Determine the size of the buffer needed to store the header information, binary 
encoded stream, and trailer using UIS$EXTRACT_HEADER, UIS$EXTRACT_ 
OBJECT or UIS$EXTRACT_REGION, and UIS$EXTRACT_TRAILER omitting the 
buffer length and buffer address parameters, 

2. Call UIS$EXTRACT_HEADER, UIS$EXTRACT_OBJECT or UIS$EXTRACT_ 
REGION, and U1S$EXTRACT_TRAILER again, specifying the previously omitted 
parameters to extract the header information, binary encoded instructions, and 
trailer and to store the data in three buffers. 

3. Use the VAX FORTRAN OPEN and WRITE statements to write the contents of 
the buffers to an external file. 

Executing the Metafile 

UIS metafiles extracted and stored in a buffer can be written to the same virtual 
display using UIS$EXECUTE. 

UIS$EXECUTE—DISPLAY creates a new virtual display and executes the metafile in 
the new display space. However, you must call UIS$CREATE_WINDOW to view 
the graphic object in the virtual display. 

15.2.5 Program Development I 

Programming Objective 

To extract the contents of a region in the virtual display and create a UIS metafile. 
Programming Tasks 

1. Initialize variables, 

2. Create a virtual display. 

3. Draw graphic objects in the virtual display. 

4. Create a display window and viewport. 

5. Determine the size of each part of the metafile. 
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6. Allocate the space in buffers for each part of the metafile. 

7. Extract the contents of the specified region in a buffer. 

8. Write the contents of the buffer to an external file. 

PROGRAM EXTRACT 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY;UISUSRDEF’ 

DATA RETLENl.RETLEN2.RETLEN3/3*0/ 

VD_ID=UIS$CREATE_DISPLAY(1.0.1.0,30.0,30.0,20.0,20.0) 
c Draw some objects 

CALL UIS$PL0T(VD_ID.0.7.0,10.0,16.0,10.0.7.0,15.0, 

2 7.0,10.0) O 

CALL UIS$ELLIPSE(VD_ID.0,20.0,20.0.9.0,5.0) Q 

CALL UIS$TEXT(VD_ID,0,’Haste and wisdom are things far odd’, 
2 11.0,15.0) 0 

c Create a display window 

WD_ID=UIS$CREATE_WIND0W(VD.ID.’SYS$W0RKSTATI0N’) 

PAUSE 

c Find out how much space to allocate for each part of the metafile 


CALL UIS$EXTRACT_HEADER(VD.ID.,.RETLENl) O 

CALL UIS$EXTRACT_REGI0N(VD.ID..,....RETLEN2) 0 

CALL UISIEXTRACT.TRAILER(VD.ID..,RETLEN3) 0 

c Virtual memory is allocated for the buffers 

STATUS=LIB$GET.VM(RETLENl.ENCODEDl) 0 

IF (.NOT.STATUS) CALL LIB$ST0P(7.VAL(STATUS)) © 
STATUS=LIB$GET.VM(RETLEN2,ENC0DED2) 0 

IF (.NOT.STATUS) CALL LIB$ST0P(7,VAL(STATUS)) 0 
STATUS=LIB$GET.VM(RETLEN3,ENC0DED3) 0 

IF (.NOT.STATUS) CALL LIB$STOP(y,VAL(STATUS)) ® 


RETLEN=RETLEN1+RETLEN2+RETLEN3 

TYPE *,’HEADER DATA’,RETLENl,’ BYTES’ 0 

TYPE *,’BINARY INSTRUCTION’,RETLEN2.’ BYTES’ 0 
TYPE ♦.’TRAILING DATA’,RETLEN3.’ BYTES’ © 

TYPE *,>N0. OF BYTES ALLOCATED = ’.RETLEN 0 

PAUSE 

C Extract the data and store it in a buffer 

CALL UIS$EXTRACT.HEADER(VD.ID.RETLENl.7.VAL(ENCODEDl) ) © 

CALL UIS$EXTRACT.REGION(VD.ID.,,..RETLEN2.%VAL(ENC0DED2)) 0 

CALL UISSEXTRACT.TRAILER(VD.ID.RETLEN3.y.VAL(ENC0DED3)) © 
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c Write the contents of the buffer to an external file 

OPEN(UNIT=10.FILE=’$DISK:[MY_DIR]METAFILE.DAT’.STATUS=’NEW’) ® 

c Call subroutine to write the contents of the buffer 

CALL BUFFERWRITE(%VAL(ENC0DED1).RETLENl.lO) ® 

CALL BUFFERWRITE (*/.VAL (ENC0DED2) , RETLEN2,10) ® 

CALL BUFFERWRITE C/.VAL (ENC0DED3) . RETLEN3,10) ® 

c Close the external file 

CLOSE(UNIT=10,STATUS=’SAVE’) ® 

END 

SUBROUTINE BUFFERWRITE(BUFFER,LENGTH,LUN) © 

IMPLICIT INTEGER(A-Z) 

BYTE BUFFER(LENGTH) 

WRITE(LUN.500)BUFFER © 

500 FORMAT(T3,17) 

RETURN 

END 

Calls to UlS$PLOT, UIS$ELLIPSE, and U1S$TEXT O © © draw objects in the virtual 
display. 

Next, you must find out how much space must be allocated for the buffers that 
will hold the header data, binary encoded stream, and trailing data. O © O. The 
variables retlenl, retlenl, and retlen3 receive the length of the header data, binary 
encoded stream, and trailing data. 

Virtual memory is allocated for the buffers and the address of each buffer is stored in 
the pointers encodedl, encoded!, and encodedS using LIB$GET_VM. © © ©. A test 
for completion status of each Run-Time Library call © © © is performed. 

The length of the header data, encoded stream, and trailing data are typed in the 
emulation window © © © as well as the total number of bytes allocated ©. 

The contents of the display list are extracted using UIS$EXTRACT_HEADER, 
UIS$EXTRACT_REGION, and UIS$EXTRACT_TRAILER stored at the location 
indicated by pointers encodedl, encoded!, and encodedS © © ©. Using the VAX 
FORTRAN built-in function %VAL, the pointers encodedl, encoded!, and encodedS are 
evaluated in terms of the actual data they store—the addresses of the starting point 
of each buffer. 

An external file is opened with the VAX FORTRAN OPEN statement for program 
output ©. 

The pointer encoded was implicitly declared as a longword integer. Therefore, you 
cannot simply write the data to the file PRIVATE.DAT. 
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The subroutine BUFFERWRITE is called ® ® ® three times to perform this task. 
Three arguments are passed in the call ®—buffer address, buffer size, and the VAX 
FORTRAN logical unit number of the output device. An array BUFFER is constructed 
from this data. 

The subroutine BUFFERWRITE writes the contents of BUFFER to the UIS metafile 
PRIVATE.DAT ©. First the header data is stored in the metafile, then the binary 
encoded stream, and, finally, the trailing data is written to PRIVATE.DAT. 

Prior to program termination, the VAX FORTRAN CLOSE statement closes the 
file 

15.2.5.1 Calling UIS$EXTRACT_HEADER, UIS$EXTRACT_REGION, and 
UIS$EXTRACT-TRAILER 

A triangle, an ellipse, and text are drawn in a virtual display as shown in Figure 15-6. 
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Figure 15-6 Original Objects Drawn in the Virtual Display 
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The terminal emulation window shown in Figure 15-7 shows buffer size information 
for metafile components. 

Figure 15-7 After Buffer Execution 

$ run extract 
FORTRAN PAUSE 
cent 

HEADER DATA 101 BYTES 

BINARY INSTRUCTION 151 BYTES 

TRAILING DATA 4 BYTES 

TOTAL NO. OF BYTES ALLOCATED = 256 

FORTRAN PAUSE 
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15.3 Display Lists and Private Data 

As mentioned earlier, display lists are created when graphics routines are executed. 
Application-specific or private data can be bound to graphic objects. The binary 
encoded instructions contained in the display list points to internal buffers that 
contain the private data. 

15.3.1 Using Private Data 

Private data is used to include some application-specific information with the graphic 
objects displayed on the workstation screen. The nature of this information is 
entirely at the discretion of the user. For example, an application that draws a 
vertical bar graph and plots relative humidity over a 24-hour period could create data 
on an hourly basis. The private data, in this case, indicating temperature or wind 
speed could be associated with each vertical bar. Private data is not displayed on 
the workstation screen and is not available to users unless extracted into a buffer or 
metafile and executed. Private data can be attached to any graphic object drawn in 
the virtual display. 
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15.3.2 Programming Options 

We will construct a program that reads data from an external file and uses it as 
private data. 

Creating Private Data 

You can create private data with UIS$PRIVATE. 

Extracting Private Data 

You can extract private data and store it in a buffer using UIS$EXTRACT_PRIVATE 
using the following procedure: 

1. Determine the size of the buffer needed to store the header information, binary 
encoded stream, and the trailer using UIS$EXTRACT_HEADER, UIS$EXTRACT_ 
PRIVATE, and UIS$EXTRACT_TRAILER omitting the buffer length and buffer 
address parameters. 

2. Call UIS$EXTRACT_HEADER, UIS$EXTRACT_PRIVATE and UIS$EXTRACT_ 
TRAILER again specifying the previously omitted parameters to extract the 
private data and store the data in a buffer. 

3. Use the VAX FORTRAN OPEN statement to write the contents of the buffer to 
an external file. 

Deieting Private Data 

You can delete private data associated with a graphic object using UIS$DELETE_ 
PRIVATE. 

15.3.3 Program Development II 

Programming Objectives 

1. To append private data to an object in the display list. 

2. To extract the private data. 

3. To create a UIS metafile containing the private data instruction. 

Programming Tasks 

1. Declare an array to receive the private data from an external file. 

2. Type out the contents of the array to verify it. 

3. Create private data and append it to the last object in the display list. 

4. Determine how large the buffers must be. 

5. Allocate memory for the buffers. 
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6. Extract the private data. 

7. Write the contents of the buffers to an external file. 

Please note that in order to run this program, you should modify the file 
specifications in the OPEN statements and construct a data file similar to DATA.DAT. 

PROGRAM PRIVATE 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY;UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

BYTE PRIV(1;23) O 

c Construct a descriptor 

INTEGER+4 PRIV_DESC(2) © 

PRIV_DESC(1)=23 

PRIV_DESC(2)=y,L0C(PRIV) © 

c Open external file containing private data 

OPEN(UNIT=8.FILE=’$DISK:[MY_DIR]DATA.DAT’,STATUS=’OLD’) O 

c Read data into array 

READ(8,50)PRIV © 

50 FORMAT(A7) 

CLOSE(UNIT=8.STATUS=’SAVE’) 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,30.0.30.0,15.0,15.0) © 

c draw the hot air balloon 

CALL UIS$SET_F0NT(VD_ID,0.2.’MY_F0NT_5’) 

INDEX=87 

CALL UIS$SET_FILL_PATTERN(VD_ID.2.2,INDEX) 

CALL UISICIRCLE(VD_ID,2,12.0,20.0,8.0) 

CALL UIS$LINE(VD_ID,2,10.0,12.0,10.0,8.0,14.0,12.0,14.0,8.0, 

2 10.0.10.0.14.0.10.0,10.0,8.0.14.0,8.0) 

c draw house 

CALL UIS$PLOT(VD_ID.0,15.0,8.0,29.0,8.0.22.0,13.0, 

2 15.0,8.0) 

CALL UIS$LINE(VD_ID,0,15.0,8.0,15.0.0.0,29.0.8.0,29.0,0.0) 
c draw door 

CALL UIS$PLOT(VD_ID.0,21.0,0.0,21.0,4.0,23.0.4.0,23.0,0.0) 

C create windows 

CALL UIS$PLOT(VD_ID,0,17.0,2.0,17.0.6.0,19.0.6.0,19.0,2.0, 

2 17.0,2.0) 

CALL UIS$LINE(VD_ID,0,17.0.4.0,19.0.4.0,18.0.2.0,18.0,6.0) 

CALL UIS$PLOT(VD_ID,0,25.0.2.0,25.0.6.0,27.0.6.0,27.0,2.0, 

2 25.0,2.0) 

CALL UIS$LINE(VD_ID.0,25.0.4.0,27.0.4.0,26.0.2.0,26.0.6.0) 
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c create chimney 

CALL UIS$LINE(VD_ID.0,26.0,11.0.28.0,11.0.26.0,11.0,26.0,10.0, 
2 28.0,11.0,28.0.9.0) 


c create smoke 

CALL UIS$ELLIPSE(VD_ID.0.27.0.13.0,2.5,1.0) 
CALL UIS$ELLIPSE(VD_ID.0.27.25,16.0.2.25.1.0) 
CALL UISSELLIPSE(VD.ID.0.27.5,19.0.2.0,1.0) 
CALL UIS$ELLIPSE(VD_ID.0.27.75,22.0.1.75,1.0) 
CALL UIS$ELLIPSE(VD_ID.0.28.0,25.0,1.5.1.0) 
CALL UIS$ELLIPSE(VD_ID.0.28.25,28.0.1.25,1.0) 
CURR_ID=UIS$GET_CURRENT_OBJECT(VD_ID) O 

c type out buffer containing private data 

TYPE *.PRIV © 


c Create private data 
FACNUM = 1 

CALL UIS$PRIVATE(vd_id,FACNUM.PRIV_DESC) © 

CALL UIS$SET_LINE_WIDTH(VD.ID.0,3,15.0) 

CALL UIS$PL0T(VD_ID.3.1.0.29.0,4.0.11.0) 

CALL UIS$CREATE_WINDOW(VD.ID,’SYS$WORKSTATION’) 

PAUSE 

c Determine size of buffer 

CALL UIS$EXTRACT_HEADER(VD.ID,..RETLENl) (D 

CALL UISSEXTRACT.PRIVATE(CURR.ID.,.RETLEN2) © 

CALL UIS$EXTRACT_TRAILER(VD.ID..,RETLEN3) ® 

RETLEN=RETLEN1+RETLEN2+RETLEN3 

TYPE *,’BUFFER SIZE FOR HEADER INFO’.RETLENl,’BYTES’ ® 
TYPE *.’BUFFER SIZE REQUIRED’,RETLEN2,’ BYTES’ © 

TYPE *,’BUFFER SIZE FOR TRAILING INFO’,RETLEN3,’BYTES © 


C Allocate the virtual memory for the buffer 

STATUS=LIB$GET.VM(RETLENl,EXT.PRIVl) © 

IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) © 
STATUS=LIB$GET_VM(RETLEN2,EXT.PRIV2) © 

IF (.NOT. STATUS) CALL LIB$STOP(7,VAL(STATUS)) © 

STATUS=LIB$GET.VM(RETLEN3.EXT.PRIV3) © 

IF (.NOT. STATUS) CALL LIB$STOP(7,VAL(STATUS)) © 

c Extract and store private data in buffer 

CALL UIS$EXTRACT.HEADER(VD.ID,RETLENl.7.VAL(EXT.PRIVl)) © 

CALL UIS$EXTRACT.PRIVATE(CURR.ID.RETLEN2,7.VAL(EXT.PRIV2)) ® 
CALL UIS$EXTRACT.TRAILER (VD.ID. RETLEN3.7.VAL (EXT.PRIV3) ) © 
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CALL BUFFERTYPE(7,VAL(EXT_PRIV2) ,RETLEN2) ® 

C Open an external file 

OPEN(UNIT=11.FILE=’$DISK:[MY.DIR]PRIVATE.DAT’,STATUS=’NEW’. © 

2 FORM=’UNFORMATTED’) 

c Write the contents of the buffer 

CALL BUFFERWRITE (y,VAL (EXT.PRIVl) . RETLENl ,11) ® 

CALL BUFFERWRITE (’/.VAL (EXT_PRIV2) , RETLEN2,11) © 

CALL BUFFERWRITE C/.VAL (EXT.PRIV3) , RETLEN3,11) © 

C Close the file 

CLOSE(UNIT=11,STATUS=’SAVE’) 

PAUSE 

END 

SUBROUTINE BUFFERWRITE(BUFFER,LENGTH,LUN) © 

IMPLICIT INTEGER(A-Z) 

BYTE BUFFER(LENGTH) 

WRITE(LUN,500)BUFFER © 

500 FORMAT(T3,17) 

RETURN 

END 

SUBROUTINE BUFFERTYPE(BUFFER,length) © 

IMPLICIT INTEGER(A-Z) 

BYTE BUFFER(length) 

TYPE *,buffer © 

RETURN 

END 

A data file DATA.DAT of private data is constructed. It consists of a sentence. 
Because each character requires a byte of storage, the total number of characters in 
the data file is specified as the upper bound of array PRIV O as well as the buffer 
length in the descriptor you must construct for UIS$PRIVATE ©. 

An external file DATA.DAT is opened © and read into the array PRIV ©. 

A circle, a triangle, and text are drawn in the virtual display ®. 

UIS$GET_CURRENT_OBJECT retrieves the identifier of the last object drawn in the 
virtual display O. 

The array PRIV is typed out to verify its contents ®. 

UIS$PRIVATE associates the sentence contained in the array PRIV with the objects 
drawn in the virtual display ®. Note that the location of the array PRIV is passed by 
descriptor ©. 
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Suppose you want to extract the data and store it in a buffer as a UIS metafile. You 
must first determine how much space the header data, binary encoded private data, 
and trailing data will occupy by calling UIS$EXTRACT_HEADER, UIS$EXTRACT_ 
PRIVATE, and UIS$EXTRACT_TRAILER without specifying the buflen and bufaddr 
arguments (D (D 

The variables retlenl, retlenl, and retlenS are typed out to reveal the size of each part 
of the display list ® <D. 

A call to LIB$GET_VM allocates virtual memory for three buffers using the value 
of retlenl, retlenl, and retlenS and stores the location of each buffer in the pointers 
ext—privl, ext—priv2, and ext—priv3, respectively © (D A test for completion 
status is performed for each Run-Time Library call © © 

If you did not use LIB$GET_VM, you would have to explicitly declare an array with 
an actual length in the beginning of the program. However, at that point in the 
program, you would have no idea how large such an array would need to be. 

A call to UIS$EXTRACT_HEADER, UIS$EXTRACT_PRIVATE, and UIS$EXTRACT_ 
TRAILER, specifying the omitted parameters, extracts the header data, binary 
encoded private data, and the trailing data and stores them in separate buffers © 

© ©. Because ext—privl, ext—priv2, and ext—priv3 are pointers, you must obtain the 
actual data that they store using the VAX FORTRAN built-in function %VAL. 

Suppose you want to look at the contents of the user buffer before you write the 
contents to an external file. 

Because the pointer ext—priv was implicitly declared a longword integer and 
functions as a pointer, we cannot simply type the data in the user. 

A subroutine BUFFERTYPE is called referencing the pointer ext—priv2 and the size 
of the buffer ©. Two arguments are passed in the call—the pointer name and the 
size of the buffer. The subroutine BUFFERTYPE reads the data from the location to 
which ext—priv2 points © and writes the data in terminal emulation window ®. 

The file PRIVATE.DAT is opened ©. 

The subroutine BUFFERWRITE © is called three times to write the header, private, 
and trailer data to the external file © © ©. Three arguments are passed in the 
call—buffer address, buffer size, and the VAX FORTRAN logical unit number of the 
output device. An array BUFFER is declared from this data and an association with 
an external file is established. 

The subroutine BUFFERWRITE writes the contents of BUFFER to the file 
PRIVATE.DAT ©. The file is closed and saved. 
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15.3.3.1 Calling UIS$PRIVATE and UIS$EXTRACT_PRIVATE 

Figure 15-8 shows the sample containing character string private data in the external 
file DATA.DAT 

Figure 15-8 Private Data 
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The private data was appended to the last ellipse drawn—the smallest cloud of a 
smoke rising from the chimney shown in Figure 15-10. 


Figure 15-10 Hot Air Balloon 
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Chapter 16 
Programming in Color 


16.1 Overview 

Until now we have assumed that the one way to change the appearance of graphic 
objects and text is through modification of attribute settings in attribute block 0. 
However, depending on the VAXstation color system you have, you can draw 
graphic objects in over 16 million colors. This chapter discusses the following topics: 

• Using color and intensity routines 

• Setting entries in virtual color maps 

• Creating shareable color maps 

• Using color map segments 

• Using color and intensity inquiry routines 

This chapter is meaningful for VAXstation users programming in either an intensity 
or color environment. 


16.2 Color and Intensity Routines—How to Use Them 

Color and intensity routines allow your application to draw graphic objects in either 
color or shades of gray. These routines create and load the structures known as 
virtual color maps and color map segments that hold the color values that your 
application use. Such routines perform the following tasks: 

• Create and delete virtual color maps 

• Load virtual color map entries with color values 

• Create and delete color map segments 

• Load entries in color map segments 

We will discuss color map segments later in this chapter. 
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16.2.1 Step 1—Creating a Virtual Color Map 

Whether you are programming in a color or an intensity environment, you must 
create a virtual color map using UIS$CREATE_COLOR_MAP. The virtual color map 
is a storage location similar to an artist's palette. Within the color map, you can store 
color values in locations known as entries. The virtual color map can vary according 
to the needs of your application. You can specify the attributes of the virtual color 
map as you see fit. 

16.2.2 Step 2—Setting Virtual Color Map Attributes 

The attributes specified for a virtual color map are either required or optional. You 
must specify the size of the virtual color map, that is, how many color map values 
it will hold. You can also specify optionally a name for the virtual color map. Other 
optional attributes are access and residency. 

Virtual Color Map Size 

As with any storage location, size is a consideration. For every color your application 
uses, you will need an entry ip the virtual color map. You can specify a maximum 
size of 32,768 entries. 

Access to Virtual Color Maps 

Another important consideration involves who should have access to your virtual 
color map. What processes should you allow to have access to your virtual color 
map? Virtual color maps can be either private or shareable. If you specify that the 
virtual color map is private, no other processes have access to it. You can designate a 
virtual color map shareable for a certain group of users or shareable among all users. 

Virtual Color Map Residency 

Another attribute that you can specify explicitly, is residency. For application- 
specific reasons, you may wish to dedicate the color resources to the execution of 
your application. Since this precludes sharing the hardware color resources among 
applications, you should use this feature carefully. 
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16.2.3 Step 3—Setting Entries in the Virtual Color Map 

At this point, depending on your color environment, your application must load 
color values into the color map entries using UIS$SET_COLOR, UIS$SET_COLORS, 
UIS$SET_INTENSITIES, or UIS$SET_INTENSITY. 

Color and intensity values are expressed as floating-point number between 0.0 and 
1.0, inclusive. The color subsystem uses the red green blue (RGB) color model. The 
colors that result from the use of color values which denote percentages of red, green, 
and blue are sometimes not readily apparent from the value chosen. Therefore, it is 
recommended that you use color setup menus of the human interface to determine 
the appropriate RGB color component values. You can use these menus as you write 
your application. 

Setting Single Entries 

If your application uses only a few colors or intensities, you may require a small 
virtual color map. In such a case, you could load each color map entry using 
UIS$SET_COLOR or UIS$SET_INTENSITY each time. 

Setting Multiple Entries 

If, on the other hand, your virtual color map is large, you can arrange your color 
map values in an array using a single call to UIS$SET_COLORS or UIS$SET_ 
INTENSITIES. 

16.2.4 Programming Options 

Whenever your application requires a range of color or intensities, you will need to 
use several of the UIS routines listed in Table 16-1. 


Table 16-1 Color and Intensity Routines 

Routine 

Function 

Virtual Color Maps 

UIS$CREATE_COLOR_MAP 

UIS$DELETE_COLOR_MAP 

Creates a virtual color map 

Deletes a virtual color map 

Loading Virtual Color Map Entries 

UIS$SET_COLOR 

UIS$SET_COLORS 

UIS$SET_INTENSITIES 

UIS$SET_INTENSITY 

Sets a single RGB color value in a virtual color map 
Sets multiple RGB color values in a virtual color map 
Sets a single intensity value in a virtual color map 

Sets multiple RGB color values in a virtual color map 
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Table 16-1 (Cont.) Color and Intensity Routines 

Routine Function 

Color Map Segments 

UIS$CREATE_COLOR_MAP_SEG Creates a color map segment 
UIS$DELETE_COLOR_MAR_SEG Deletes a color map segment 


16.2.5 Program Development I 

Programming Objective 

To create and load a color map with single entries. 

Programming Tasks 

1. Establish a size for the virtual color map. 

2. Create the virtual color map. 

3. Create a virtual display. 

4. Create a display window and viewport. 

5. Load a single color map entry with one color value using UIS$SET_COLOR. 

PROGRAM SINGLE.ENTRY 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL J.K 

DATA J/17.0/ O 

DATA K/16/ © 

DATA VCM_SIZE/8/ 

VCM_ID=UIS$CREATE_COLOR_MAP(VCM.SIZE) © 

VD_ID=UIS$CREATE_DISPLAY(1.0.1.0,40.0,40.0,15.0,15.0,VCM.ID) O 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’,’WINDOW #1’) 

CALL UIS$SET_C0L0R(VD_ID,0,0.40,0.30.0.0) © 

CALL UIS$SET_C0L0R(VD_ID.1,0.5,0.5.0.5) © 

CALL UIS$SET_C0L0R(VD_ID.2,0.5,0.25.0.5) © 

CALL UIS$SET_COLOR(VD_ID.3.0.0.0.7,0.3) © 

CALL UIS$SET_C0L0R(VD_ID,4.0.25,0.25.0.9) © 

CALL UIS$SET_C0L0R(VD_ID.5.0.90.0.5.0.0) © 

CALL UIS$SET_C0L0R(VD_ID,6,0.80,0.30.0.0) ® 

CALL UIS$SET_C0L0R(VD_ID.7,0.35,0.65,0.95) © 
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CALL UIS$SET_WRITING_INDEX(VD_ID.0,9,2) ® 

CALL UIS$SET_WRITING_INDEX(VD_ID.0.10.3) ® 

CALL UIS$SET_WRITING_INDEX(VD_ID.0.11.4) ® 

CALL UIS$SET_WRITING_INDEX(VD_ID.0.12.5) <D 

CALL UIS$SET_WRITING_INDEX(VD_ID.0.13.6) ® 

DO 1=9,13.1 

CALL UIS$CIRCLE(VD_ID.I.J.20.0.10.0) ® 

J=J+2.0 

ENDDO 

PAUSE 

DO 1=9.13 

CALL UIS$CIRCLE(VD_ID,I,21.0.K.10.0) ® 

K=K+2.0 

ENDDO 

PAUSE 

END 

The counters j and k are declared and initialized O ©. 

An eight-entry virtual color map is created with no attributes specified ®. 

The virtual color map is associated with the virtual display in UIS$CREATE_ 
DISPLAY O during creation of the virtual display. 

Each color value is loaded into a virtual color map using successive calls to UIS$SET_ 
COLOR 0OO®®<D®®. 

The default writing color attribute setting in attribute block 0 is modified such that 
five new default writing colors are associated with a virtual color map entry ® <D 0 

0 0 . 

The atb argument in the call to UIS$CIRCLE within the DO loop references the 
modified attribute block. As a result, five circles are drawn horizontally 0 each with 
a different default writing color. 

Five circles are drawn vertically 0 using the same colors as the horizontally drawn 
circles. 
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16.2.6 Program Development II 

Programming Objective 

To create and load a color map with more than one entry at a time. 

Programming Task 

1. Load the arrays with color component values. 

2. Establish color map size. 

3. Load eight color map entries in a single call using UIS$SET_COLORS. 

PROGRAM MULTIPLE.ENTRY 
IMPLICIT INTEGER(A-Z) 

INCLUDE 'SYS$LIBRARY;UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL J.K 

REAL R_VECT0R(8).G_VECTOR(8).B.VECTOR(8) O 

DATA J/17.0/ © 

DATA K/16/ © 

DATA R_VECT0R/0.40.0.50,0.50,0.0,0.25,0.90,0.80,0.35/ © 

DATA G_VECT0R/0.30.0.50,0.25,0.70,0.25,0.50,0.30,0.65/ © 

DATA B_VECT0R/0.0.0.50,0.50,0.30,0.90,0.0,0.0,0.95/ © 

DATA VCM_SIZE/8/ 

VCM_ID=UIS$CREATE_C0L0R_MAP(VCM.SIZE) © 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,40.0,40.0,15.0,15.0,VCM.ID) ® 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$W0RKSTATI0N’,’COLOR') 

CALL UIS$SET_C0L0RS(VD_ID,0,8.R_VECT0R,G_VECT0R,B_VECT0R) © 

CALL UIS$SET_WRITING_INDEX(VD_ID.0,9,2) 

CALL UIS$SET_WRITING_INDEX(VD_ID.0,10,3) 

CALL UIS$SET_WRITING_INDEX(VD_ID.0,11,4) 

CALL UIS$SET_WRITING_INDEX(VD_ID.0,12,5) 

CALL UIS$SET_WRITING_INDEX(VD_ID.0,13,6) 

DO 1=9,13,1 

CALL UIS$CIRCLE(VD_ID.1,3,20.0.10.0) 

J=J+2.0 

ENDDO 

PAUSE 

DO 1=9,13 

CALL UIS$CIRCLE(VD_ID.I,21.0,K,10.0) 

K=K+2.0 

ENDDO 

PAUSE 


END 
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Three arrays are declared O to hold eight R, G, and B color component values each. 
The counters ; and k are declared and initialized O O. 

The arrays R_VECTOR, G_VECTOR, and B_VECTOR are loaded with color 
component values O O ©. 

An eight-entry virtual color map is created O and associated with a newly created 
virtual display ©. 

The R, G, and B color component values stored in the arrays are loaded in the virtual 
color map using a single call to UIS$SET_COLORS ®. 

The remaining portions of the program are identical to the previous program 
SINGLE-ENTRY. 

16.2.6.1 Program Development III 

Programming Objective 

To create a shareable color map. 

Programming Task 

1. Load arrays containing color component values. 

2. Create the color map attributes list specifying the shareable attribute. 

3. Create a virtual display specifying a name for the color map. 

4. Create a display window and display viewport. 

5. Load color values into the color map. 

6. Program 2 must perform steps 2 through 4 and reference the name of the color 
map specified in Program 1, 

PROGRAM SHAREABLE.MAP 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

REAL J.K O 

REAL R_VECT0R(8).G_VECT0R(8),B_VECT0R(8) 

INTEGER+4 VCM.ATTRIBUTES(3) © 

DATA J/17.0/ © 

DATA K/16/ O 

DATA R_VECT0R/0.40,0.50,0.50,0.0,0.25,0.90,0.80/ 

DATA G_VECT0R/0.30,0.50,0.25,0.70,0.25,0.50,0.30/ 

DATA B_VECT0R/0.0,0.50,0.50,0.30,0.90,0.0,0.0/ 

DATA VCM_SIZE/8/ 

VCM.ATTRIBUTES(1)=VCMAL$C_ATTRIBUTES © 

VCM.ATTRIBUTES(2)=VCMAL$M_SHARE © 

VCM.ATTRIBUTES(3)=VCMAL$C.END.0F.LIST 


© 
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VCM_ID=UIS$CREATE_COLOR_MAP(VCM.SIZE,’LIVING.COLOR’.VCM.ATTRIBUTES) € 
VD_ID=UIS$CREATE_DISPLAY(1.0,1.0.40.0,40.0.15.0,15.0,VCM_ID) O 
WD_ID=UIS$CREATE_WINDOW(VD_ID.*SYS$WORKSTATION’.’PROCESS #1’) 

CALL UIS$SET_C0L0RS(VD.ID.0.8.R.VECTOR.G.VECTOR.B.VECTOR) 

CALL UIS$SET_WRITING_INDEX(VD.ID.0,9.2) ® 

CALL UIS$SET_WRITING«INDEX(VD.ID.0,10,3) 

CALL UIS$SET_WRITING_INDEX(VD.ID,0,11,4) 

CALL UIS$SET.WRITING.INDEX(VD.ID,0,12.5) 

CALL UIS$SET_WRITING.INDEX(VD.ID,0.13,6) 

DO 1=9,13,1 

CALL UIS$CIRCLE(VD.ID,I,J,20.0,10.0) 

J=J+2.0 

ENDDO 

VD.ID2=UIS$CREATE.DISPLAY(1.0,1.0,40.0,40.0,15.0,15.0,VCM.ID) 
WD.ID2=UIS$CREATE.WIND0W(VD.ID2.’SYS$WORKSTATION’.’WINDOW #2’) 

CALL UIS$SET.WRITING.INDEX(VD.ID2.0.9.2) ® 

CALL UIS$SET.WRITING.INDEX(VD.ID2.0,10,3) 

CALL UIS$SET.WRITING.INDEX(VD.ID2.0.11,4) 

CALL UIS$SET.WRITING.INDEX(VD.ID2.0,12,5) 

CALL UIS$SET.WRITING.INDEX(VD.ID2.0.13,6) 

DO 1=9,13,1 

CALL UIS$CIRCLE(VD.ID2,I,21.0.K.10.0) 

K=K+2.0 

ENDDO 

PAUSE 

END 

The counters j and k are declared and initialized O O O. 

An integer array VCM_ATTRIBUTES is declared to have three elements ©. 

The array elements are assigned attribute values defined by UIS constants @ ® 

O. The structure contains an attribute code followed by a longword value for that 
attribute. The final element contains a longword 0 to terminate the list. 

An eight-entry virtual color map is created using UIS$CREATE_COLOR_MAP and 
the array VCM_ATTRIBUTES is used as an argument ®. 

The newly created virtual display references the virtual color map ®. Objects drawn 
in the virtual display can use this virtual color map. 

Different default writing color are defined ® as in previous programs simply to 
highlight and differentiate the objects drawn. 
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A second virtual display is created The second call to UIS$CREATE—DISPLAY 
references the same virtual color map identifier as the first. Both virtual displays will 
share the use of color value assignments in this virtual color map. 

However, you must call UIS$SET_WRIT1NG—INDEX ® again to change the default 
setting of the writing color so that objects will be drawn in colors identical to those 
drawn in the first virtual display. 

Here is a portion of a second program that uses the virtual color map that uses the 
virtual color map LIVING—COLOR in the program SHAREABLE—MAP. 


PROGRAM SECOND.PROGRAM 


INTEGER+4 VCM.ATTRIBUTES(3) O 
DATA VCM_SIZE/8/ © 

VCM_ATTRIBUTES(1)=VCMAL$C_ATTRIBUTES 
VCM.ATTRIBUTES(2)=VCMAL$M_SHARE 
VCM.ATTRIBUTES(3)=VCMAL$C_END_OF_LIST 

VCM_ID=UIS$CREATE_COLOR_MAP(VCM.SIZE.’LIVING.COLOR’.VCM.ATTRIBUTES)© 
VD_ID2=UIS$CREATE_DISPLAY(1.0,1.0,35.0,35.0,10.0,10.0,VCM.ID) 

WD_ID2=UIS$CREATE_WIND0W(VD_ID2,’SYS$W0RKSTATI0N’,’PROCESS #2) 


An array of virtual color map attributes specifying the same attributes as those 
indicated in the preceding program SHAREABLE—MAP O. The application 
SECOND—PROGRAM must declare the virtual color map size © as this is a required 
argument in UIS$CREATE—COLOR—MAP. 

The shareable color map is referenced by name in a call to UIS$CREATE—COLOR- 
MAP ©. 


16.3 Color Map Segments 

Through the use of color map segments, you can control the binding of the virtual 
color map to the hardware color map. 



16-10 


Programming in Color 


16.3.1 Programming Options 

Creating and Deleting Color Map Segments 

You can create and delete color map segments using UIS$CREATE_COLOR_MAP_ 
SEG and UIS$DELETE_COLOR_MAP_SEG. 


16.3.2 Program Development 

The program COLOR_SEG is a portion of a longer program and shows how to bind 
your virtual color map to the hardware color map. 

PROGRAM C0L0R_SEG 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

INTEGER*4 VCM.ATTRIBUTES(3) O 

DATA VCM_SIZE,PLACEMENT_DATA/8.16/ O 


VCM_ATTRIBUTES(1)=VCMAL$C_ATTRIBUTES ® 

VCM.ATTRIBUTES(2)=VCMAL$M_N0BIND O 

VCM.ATTRIBUTES(3)=VCMAL$C_END_OF_LIST @ 

VCM_ID=UIS$CREATE_COLOR_MAP(VCM.SIZE..VCM.ATTRIBUTES) O 

CMS_ID=UIS$CREATE_COLOR_MAP_SEG(VCM_ID,’SYS$W0RKSTATI0N’, 

2 UIS$C_COLOR_EXACT.PLACEMENT_DATA) O 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,30.0,30.0.10.0,10.0.VCM_ID) 
WD_ID=UIS$CREATE_WIND0W(VD_ID.’SYS$W0RKSTATI0N’) 


Two declarations are established—an array VCM__ATTRIBUTES is declared O and 
the virtual color map size is initialized to 8 ©. 

Because the color map segment is created with exact placement, the placement—data 
argument of UIS$CREATE—COLOR—MAP_SEG must be initialized to the starting 
index in the hardware color map where binding is to occur. 

The elements of array VCM—ATTRIBUTES are assigned an attribute code 0, an 
attribute value VCMAL$M—NOBIND O, and a terminating value 0. 

UIS$CREATE—COLOR—MAP is called before any other UIS routine. 



Programming in Color I 6-11 


16.3.3 Calling UIS$CREATE_COLOR-MAR_SEG 

No special graphics effects are displayed on the VAXstation screen. 

16.4 Color and Intensity Inquiry Routines 

As mentioned previously in Chapter 12, certain routines called inquiry routines 
provide application with status information. There are several UIS color and intensity 
routines that return information to the application. Color and intensity inquiry 
routines return information about the color setup, virtual color map, and hardware 
color map. Such information can be used as direct input to your application. 

16.4.1 Programming Options 

Your application can use one or more inquiry routines, where appropriate. 

Table 16-3 lists color and intensity inquiry routines. 


Table 16-3 Color and Intensity Inquiry Routines 


Routine 

Information Returned 

Virtual Color Map 

UIS$GET_COLOR 

UIS$GET_COLORS 

UIS$GET_INTENSITIES 

UIS$GET_INTENSITY 

Single RGB value from a virtual color map 

Multiple RGB values from a virtual color map 

Multiple intensity values from a virtual color map 
Single intensity value from a virtual color map 

Hardware Color Map 

UIS$GET__HW_COLOR_INFO 

Device type; number of indexes; number of colors; bits 
of precision for R, G, and B values; reserved entries; 
and regeneration characteristics. 

Color Value Conversion 

UIS$HLS_TO_RGB 

UIS$HSV_TO_RGB 

UIS$RGB_TO_HLS 

UIS$RGB_TO_HSV 

Converts HLS color values to RGB color values 

Converts HSV color values to RGB color values 

Converts RGB color values to HLS color values 

Converts RGB color values to HSV color values 
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Table 16-3 (Cont.) Color and Intensity Inquiry Routines 

Routine 

Information Returned 

Workstation Standard Colors 

UIS$GET_WS_COLOR 

UIS$GET_WS_INTENSITY 

Workstation standard RGB color value 

Workstation standard intensity value 

Color Setup 

UIS$GET_BACKGROUND_INDEX 

UIS$GE1_WRITING -INDEX 

UIS$GET_WRITING_MODE 

Window background index 

Window foreground index 

Writing mode 


16.4.2 Program Development I 

Programming Objective 

To retrieve hardware color map information. 

Programming Tasks 

1. Create a virtual color map. 

2. Create a virtual display. 

3. Create a display window and viewport. 

4. Obtain the number of color map indices, possible colors, maps, bits of precision 
for each color component, and reserved entries. 

PROGRAM GET.INFO 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYSSLIBRARY:UISUSRDEF’ 

REAL J.K 

REAL R_VECT0R(8),G_VECT0R(8).B_VECT0R(8) 

REAL RETR_VECT0R(8),RETG_VECT0R(8),RETB_VECTOR(8) 

INTEGER+4 VCM.ATTRIBUTES(3) 

DATA J/17.0/ 

DATA K/16/ 

DATA R_VECT0R/0.40.0.50,0.50,0.0,0.25,0.90,0.80,0.35/ 

DATA G_VECT0R/0.30.0.50,0.25,0.70,0.25,0.50,0.30,0.65/ 

DATA B_VECT0R/0.0.0.50,0.50,0.30,0.90,0.0,0.0,0.95/ 

VCM_ATTRIBUTES(1)=VCMAL$C_ATTRIBUTES 
VCM.ATTRIBUTES(2)=VCMAL$M_SHARE 
VCM.ATTRIBUTES(3)=VCMAL$C_END_0F_LIST 









Programming in Color 16-13 


VCM_ID=UIS$CREATE_COLOR_MAP(VCM.SIZE.VCM.ATTRIBUTES) 
VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,40.0.40.0.15.0,15.0,VCM.ID) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’.’COLOR’) 

CALL UIS$SET_C0L0RS(VD_ID.0.8.R_VECTOR,G.VECTOR,B.VECTOR) 

CALL UIS$SET_WRITING_INDEX(VD_ID,0,9,2) 

CALL UIS$SET_WRITING_INDEX(VD.ID,0,10,3) 

CALL UIS$SET_WRITING_INDEX(VD.ID.0,11,4) 

CALL UIS$SET_WRITING_INDEX(VD.ID,0,12,5) 

CALL UIS$SET.WRITING.INDEX(VD.ID,0,13,6) 

CALL UISSGET.COLORS(VD.ID,0.8,RETR.VECTOR,RETG.VECTOR.RETB.VECTOR) O 
TYPE 50 

50 format(T8.’RED’.T18,’GREEN’,T30,’BLUE’) 

TYPE 100.RETR.VECTOR.RETG.VECTOR,RETB.VECTOR 
100 F0RMAT(F11.3,F11.3.F11.3) 

CALL UIS$GET_HW.COLOR_INFO(,. 

2 INDICES.COLORS.MAPS.RBITS.GBITS.BBITS..RES.INDICES) © 

TYPE 150.INDICES,COLORS 

150 FORMAT(T2.’NO. OF INDICES=’.13.T22,’NO. OF COLORS=’.18) 

TYPE 200,MAPS 

00 FORMAT(T2.’NO.OF MAPS=’.13) 

TYPE 225,RBITS,GBITS.BBITS 

225 FORMAT(T2.’NO. OF BITS OF PRECISION’,T28.’RED’.13.T37.’GREEN’,13, 

2 T48.’BLUE’.13) 

TYPE 250,RES.INDICES 

250 FORMAT(T2.’NO. OF RESERVED ENTRIES’,13) 

TYPE*.’VCM Indexes Used In Virtual Display 1’ 

DO 1=9,13,1 

CALL UISSCIRCLE(VD.ID.I.J.20.0.10.0) 
INDEX=UIS$GET.WRITING_INDEX(VD_ID,I) © 

TYPE*,INDEX 

J=J+2.0 

ENDDO 

VD.ID2=UIS$CREATE.DISPLAY(1.0,1.0,40.0,40.0,15.0,15.0,VCM.ID) 
WD.ID2=UIS$CREATE_WIND0W(VD.ID2,’SYS$WORKSTATION’.’WINDOW #2’) 

CALL UIS$SET.WRITING.INDEX(VD.ID2.0,9,2) 

CALL UIS$SET_WRITING.INDEX(VD.ID2.0,10,3) 

CALL UIS$SET.WRITING.INDEX(VD.ID2,0,11,4) 

CALL UIS$SET_WRITING.INDEX(VD.ID2.0,12,5) 

CALL UIS$SET.WRITING.INDEX(VD.ID2,0,13,6) 
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TYPE*,’VCM Indexes Used In Virtual Display 2’ 

DO 1=9,13 

CALL UIS$CIRCLE(VD_ID2.I,21.0,K,10.0) 

INDEX=UIS$GET_WRITING_INDEX(VD_ID2.1) O 

TYPE*,INDEX 

K=K+2.0 

ENDDO 

PAUSE 

END 

With the inclusion of only three inquiry routines, a great deal of information is 
returned. A call to UIS$GET_COLORS O returns the R, G, and B color component 
values in the color map entries of the virtual color map. 

A call to UIS$GET_HW_COLOR_INFO © returns the number of binary bits of 
precision for R, G, and B color map values. In addtion, total number of hardware 
color map entries as well as the number of reserved entries. 

Writing color information must be returned from two locations in the program. 

The first call to UIS$GET_WRITING—INDEX within the DO loop ® returns all the 
default writing indexes as they are being used in the first virtual display. 

The second call to UIS$GET_WRITING-INDEX O returns each writing index used 
to draw graphic objects in the second virtual display. 

16.4.2.1 Calling UIS$GET-COLORS, UIS$GET-HW-COLOR-iNFO, 
UIS$GET-WRITING-INDEX 

Figure 16-1 shows the information returned in the user's emulation window. 
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Figure 16-1 Different Types of Information Returned from Inquiry Routines 
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16.4.3 Program II—Creating an HSV Color Wheel 

PROGRAM COLOR.WHEEL 
c 

c This program draws a color wheel once and then continually 
c changes its appearance by updating the virtual color map. 
c 

IMPLICIT INTEGER*4(A-Z) 

PARAMETER DISPLAY_SIZE=4.0*2.54 
REAL*4 R.G.B.H.L.S.V,START.DEG,END.DEG 
REAL*4 R_VECT0R(0:255),G.VECTOR(0:255).B.VECTOR(0:255) 
INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 
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c 

c Find out some information about the workstation color characteristics 
c 

CALL UIS$GET_HW_C0L0R_INF0(,.INDICES,.MAPS,,,.,RES_INDICES,REGEN) 
c 

c Only attempt to run this program on color map hardware systems, 
c 

IF (MAPS .EQ. 0 .OR. REGEN .NE. UIS$C_DEV_RETRO) STOP 
c 

c Make the virtual color map size dependent upon the available 
c hardware, but no greater than 64 entries 
c 

MAP_SIZE=MIN(INDICES-RES_INDICES. 64) 
VCM_ID=UIS$CREATE_COLOR_MAP(MAP_SIZE) 
c 

c Create the virtual display and a single window 
c 

VD_ID=UIS$CREATE_DISPLAY(0.0. 0.0, 1.0, 1.0, 

1 DISPLAY_SIZE, DISPLAY.SIZE, VCM.ID) 

WD_ID=UIS$CREATE_WINDOW(VD_ID. ’SYS$WORKSTATION’) 


c 

c Establish some attributes for drawing 
c 

CALL UIS$SET_ARC_TYPE(VD_ID, 0. 1, UIS$C_ARC_PIE) 

CALL UIS$SET_FONT(VD_ID, 1, 1, ’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD_ID. 1. 1. PATT$C_FOREGROUND) 
c 

c Set window background to black and draw wedges of a circle, 
c The initial colors of the wedges are determined by traversing 
c 360 degrees around the HSV color model, varying H, while S and 
c V are both 1.0. 
c 

CALL UIS$SET_COLOR(VD_ID. 0, 0.0, 0.0, 0.0) 

DO I=1.MAP_SIZE-1 

START_DEG=(I-1)*(360.O/FLOAT(MAP_SIZE-1)) 

END_DEG=START_DEG+(360.O/FLOAT(MAP_SIZE-1)) 

CALL UIS$HSV_TO_RGB(START_DEG. 1.0, 1.0, R. G, B) 

CALL UIS$SET_COLOR(VD_ID. I. R, G. B) 

CALL UIS$SET_WRITING_INDEX(VD_ID. 1. 1. I) 

CALL UIS$CIRCLE(VD_ID, 1, 0.5, 0.5, 0.4, START.DEG, END.DEG) 
END DO 
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c 

V=1.0 

c 

c The next set of sequential and nested loops 
c traverse the HSV color model cone, 
c 

100 CONTINUE 
c 

c Vary S from 1.0 to 0.0 in 0.01 increments 
c 

DO 18=99,0,-1 
S=FL0AT(IS)/100.0 
c 

DO I=1,MAP_SIZE-1 

START_DEG=(I-1)*(360.0/FL0AT(MAP_SIZE-l)) 

IF (S .EQ. 0.0) START_DEG=UIS$C_COLOR_UNDEFINED 
CALL UIS$HSV_TO_RGB(START_DEG, S, V, 

1 R.VECTORd), G_VECT0R(I), B_VECT0R(I)) 

END DO ! I 

CALL UIS$SET_COLORS(VD_ID, 1, MAP_SIZE-1, 

1 R.VECTORd), G.VECTORCl), B_VECT0R(1)) 

c 

end do ! s=l.0,0.0 


c Vary V from 1.0 to 0.0 in 0.01 increments 
c 

DO IV=99,0,-1 
V=FLOATdV)/100.0 
c 

DO I=1,MAP_SIZE-1 

START_DEG=(I-1)*(360.O/FLOAT(MAP_SIZE-1)) 

IF (S .EQ. 0.0) START_DEG=UIS$C_COLOR_UNDEFINED 
CALL UIS$HSV_TO_RGB(START_DEG, 8, V, 

1 R.VECTORd), G.VECTORd), B_VECT0R(I)) 

END DO ! I 

CALL UI8$8ET_C0L0R8(VD_ID, 1, MAP_8IZE-1, 

1 R.VECTORd), G.VECTOR(l), B_VECT0R(1)) 


c 


END DO 


! V=l.0,0.0 
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c 

c Vary V from 0.0 to 1.0 in 0.01 increments 
c 

DO IV=1,100. 1 
V=FL0AT(IV)/100.0 
c 

DO I=1,MAP_SIZE-1 

START_DEG=(I-1)*(360.0/FL0AT(MAP_SIZE-l)) 

IF (S .EQ. 0.0) START_DEG=UIS$C_COLOR_UNDEFINED 
CALL UIS$HSV_TO_RGB(START_DEG. S. V. 

1 R.VECTORd), G.VECTORd), B.VECTORd)) 

END DO ! I 

CALL UIS$SET_COLORS(VD_ID. 1. MAP_SIZE-1. 

1 R.VECTORd), G_VECT0R(1). B_VECT0R(1)) 

c 

END DO ! V=0.0,1.0 

c 

c Vary S from 0.0 to 1.0 in 0.01 increments 
c 

DO 18=1,100,1 
S=FL0ATdS)/100.0 
c 

DO I=1,MAP«SIZE-1 

START_DEG=(I-1)♦(360.O/FLOAT(MAP_SIZE-1)) 

IF (S .EQ. 0.0) START_DEG=UIS$C_COLOR_UNDEFINED 
CALL UIS$HSV_TO_RGB(START_DEG, S, V, 

1 R.VECTORd), G.VECTORd), B_VECTOR(I)) 

END DO ! I 

CALL UIS$SET_COLORS(VD_ID. 1, MAP_SIZE-1, 

1 R.VECTORd), G.VECTORd), B_VECT0R(1)) 

c 

END DO ! 8=0.0,1.0 

c 

c Repeat H8V color cone traversal indefinitely 
c 

GOTO 100 
c 

END 



Chapter 17 

Asynchronous System Trap Routines 

17.1 Overview 

Frequently, an application program relies on certain run-time events to trigger the 
execution of an application-specific task. Such run-time events can range from power 
failure to simply striking a key on the keyboard. Several UIS routines enable this 
type of behavior for the duration of the program or until the enabling UIS routine is 
explicitly disabled. Such routines enable the use of asynchronous system trap (AST) 
routines. This chapter discusses AST routines and how they can be used to perform 
the following tasks: 

• Creating a virtual keyboard 

• Creating a pointer pattern 

• Using a pointer 

• Resizing a display window 

• Closing a display window 

• Shrinking a display viewport to an icon 

The use of AST routines is not restricted to the tasks listed here. 

17.1.1 Using AST Routines 

Generally speaking, certain UIS routines associate or, bind, a specific run-time 
event or action to a subroutine. When that action occurs, control passes from the 
main program to a user-written subroutine. The subroutine then performs some 
application-specific task. When the subroutine completes execution, control is 
transferred to the next statement in the main program. However, the association 
between the run-time event and the execution of the subroutine remains in effect. If 
the action occurred again during program execution, the subroutine would be called 
again. The process executing the main program is suspended when the run-time 
event occurs and until the subroutine completes execution. Thus, execution of the 
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subroutine occurs asynchronously with respect to execution of the main program. 
The user-written subroutine is known as an asynchronous system trap routine or AST 
routine. 

As with any subprogram or subroutine, the AST routine can be coded within the 
main program according to the conventions of the particular programming language 
or separately as a module in a library. However, to make use of such modules, you 
must compile and link them with your program. 

17.1.2 AST-Enabling Routines 

Several UIS routines enable AST routine execution whenever a particular run-time 
event occurs. The actual event may involve the keyboard, pointer, or the occurrence 
of a program-related event, such as the movement or resizing of a window. Such 
AST-enabling routines reference AST routines in their argument lists. Table 17-1 lists 
each AST-enabling routine and the event that triggers AST routine execution. 


Table 17-1 AST-Enabling Routines 


Routine 

Event 

UIS$SET_ADDOPT_AST 

An additional option is chosen using the human 
interface. 

UIS$SET_BUTTON_AST 

A button is depressed or released on a pointer 
device. 

UIS$SET_CLOSE_AST 

A display window is deleted with the human 
interface. 

UIS$SET_TB_AST 

A digitizer is moved within a specified data region 
on the tablet. 

UIS$SET_EXPAND_ICON_AST 

An icon is expanded to display viewport with the 
user interface. 

UIS$SET_G AIN _KB_AST 

A virtual keyboard is bound to a physical keyboard. 

UIS$SET_KB_AST 

A key is struck. 

UIS$SET_LOSE_KB_AST 

A virtual keyboard is disconnected from a physical 
keyboard. 

UIS$SET_MOVE_INFO_AST 

A window is moved in the virtual display. 

UIS$SET_POINTER_AST 

A pointer moves into or exits an area of the virtual 
display. 

UIS$SET_RESIZE_AST 

A display window is resized with the human 
interface. 

UIS$SET_SHRINK_ICON_TO_AST 

A display viewport is shrunk with the human 
interface. 
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17.2 Using Keyboard and Pointer Devices 

The keyboard and pointer devices are resources for use within your application 
program. The keyboard and pointer are mentioned here to illustrate routines that 
can make use of input from such workstation peripheral devices during application 
program execution. An effective way of using keyboard and pointer devices is in 
conjunction with AST routines. 

17.2.1 Using AST Routines with Virtual Keyboards 

You can use your keyboard as a virtual device whose characteristics are transportable 
from virtual display to virtual display. When the keyboard is used as a virtual 
device, you can create an unlimited number of them (subject to system and process 
resources) with different characteristics and associate each with any virtual display 
you choose. 

17.2.1.1 Step 1—Creating a Virtual Keyboard 

A virtual keyboard is created using UIS$CREATE_KB. There is no limit to the 
number of virtual keyboards you can create. 

17.2.1.2 Step 2—Binding the Virtual Keyboard to the Display Window 

In addition, you must bind the virtual keyboard to a specified display window using 
UIS$ENABLE_VIEWPORT_KB or UIS$ENABLE_KB. UIS$ENABLE-VIEWPORT- 
KB and UIS$ENABLE—KB also define how the physical keyboard and the virtual 
keyboard are assigned to each other. 

If your display screen contains one or more display viewports and you have 
assigned virtual keyboards to their associated display windows, you can move 
from display viewport to viewport through the assignment list using the I cycle I key. 
An assignment list of display windows keeps track of which viewport is active. 

A viewport is active when the KB icon background color on the viewport is 
highlighted. The physical keyboard is now assigned to a virtual keyboard. The 
virtual keyboard and all enabled characteristics can then be used with the physical 
keyboard. You can bind more than one display window to the same virtual 
keyboard. In this case, the KB icons in all display viewports are highlighted at 
the same time when the desired windows are assigned a physical keyboard. 

Table 17-2 shows how each routine performs physicaTto-virtual keyboards 
assignments. 
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Table 17-2 Connecting Physical Keyboards and Virtual Keyboards 


Routine 

Function 

UIS$EN ABLE _VIEWPORT_KB 

UIS$ENABLE_KB 

Adds the display window to the assignment list. Use the 

1 CYCLE 1 kev to move from viewport to viewport. 

Places the display window at the top of the assignment 
list and is active. Use the 1 CYCLE | kev to move to other 
viewports. 


To terminate the binding of the specified virtual keyboard to the physical keyboard, 
use UIS$DISABLE_VIEWPORT_KB or UIS$DISABLE_KB. Table 17-3 shows how 
each routine terminates physical-to-virtual keyboard assignments. 


Table 17-3 Disconnecting Physical Keyboards and Virtual Keyboards 

Routine 

Function 

UIS$DIS ABLE _VIEWPORT_KB 

UIS$DISABLE_KB 

Removes a display window from the assignment 
list. Invoke UIS$ENABLE_VIEWPORT_KB or 
UIS$ENABLE_KB to make the viewport active. 

Places a display window at the bottom of the assignment 
list. Use the 1 CYCLE | kev to make the viewport active. 


17.2.1.3 step 3—Enabling Virtual Keyboard AST Routines 

Even though you have created a virtual keyboard and you have bound it to a 
specified display window, you still cannot write characters to that display window. 
You must associate the act of striking a key with the action taken by a subroutine 
using UIS$SET_KB_AST. 

17.2.2 Programming Options 

After you have created the virtual keyboard, your application may verify successful 
connection with the physical keyboard. You may want to be notified in the event 
such connections are made or broken. These and other options are available to your 
application. 

Gaining and Losing Virtual Keyboards 

Connecting and disconnecting virtual keyboards may occur many times within your 
application program. These events may be so significant that whenever a virtual 
keyboard is disconnected or lost, you may want your program to initiate some 
action through a subroutine. For example, UIS$SET_GAIN_KB_AST and UIS$SET_ 
LOSE_KB__AST enable AST routines that could allow your program to perform 
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housekeeping functions such as deleting unused virtual keyboards, display windows, 
and display viewports when a virtual keyboard is disconnected. 

Enabling and Disabling Keyboard Characteristics 

Keyboard characteristics are assigned to specific virtual keyboards using UIS$SET_ 
KB_ATTRIBUTES. 

Testing Physical Keyboards 

You can verify the connection between a specified virtual keyboard and the physical 
keyboard with UIS$TEST_JKB. 

Deleting Virtual Keyboards 

To delete a virtual keyboard, use UIS$DELETE_KB. 

17.2.3 Program Development 

Programming Objectives 

To type keyboard characters directly to the virtual display using AST routines. 

Programming Tasks 

1. Declare subroutine and the appropriate variables to be included in the 
COMMON statement, 

2. Create a virtual display. 

3. Create a virtual keyboard. 

4. Create a display window and viewport. 

5. Bind the virtual keyboard to the display window. 

6. Enable keyboard AST routines using UIS$SET_KB_AST. 

7. Create a subroutine to send each keystrike to the virtual display. 

PROGRAM AST 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

LOGICAL*1 KEYBUF(4) 

EXTERNAL KEYSTRIKE O 

COMMON KB_ID,VD_ID,KEYBUF,WD_ID.COUNT O 

VD_ID=UIS$CREATE_DISPLAY(1.0,1.0,31.0,31.0,20.0.5.0) 
KB_ID=UIS$CREATE_KB(’SYS$W0RKSTATI0N’) @ 
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WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’.’KEYBOARD AST’) 
CALL UIS$ENABLE_VIEWPORT_KB(KB_ID.WD_ID) O 

CALL UIS$SET_ALIGNED_POSITION(VD_ID.1,1.0,30.0) 

C0yNT=0 

CALL UIS$SET_KB_AST(KB_ID.KEYSTRIKE.O.KEYBUF) 0 

CALL SYS$HIBER() 0 

END 

SUBROUTINE KEYSTRIKE O 
IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

LOGICAL*! KEYBUF(4) 

COMMON KB_ID.VD_ID,KEYBUF.WD_ID.COUNT © 

STRUCTURE/TEXT/ 0 

INTEGER*2 BUFLEN,BUFCODE 
INTEGER*4 BUFADR 
END STRUCTURE 

RECORD/TEXT/DESC 0 

DESC.BUFLEN=1 

DESC. BUFADR=7.L0C (KEYBUF) 0 

STATUS=UIS$TEST_KB(KB_ID) 0 

CALL UIS$SET_FONT(VD_ID,1.2,’MY_F0NT_13’) 

IF ((COUNT .EG). 60) .OR. (KEYBUF(1) .EQ. 13)) THEN 0 
CALL UIS$NEW_TEXT_LINE(VD_ID,2) 

C0UNT=0 

ELSE 

CALL UIS$TEXT(VD_ID.2.DESC) 

C0UNT=C0UNT+1 
END IF 

RETURN 

END 

The name of the AST routine KEYSTRIKE is declared O using the EXTERNAL 
statement. The EXTERNAL statement defines the symbolic name of the routine as an 
address. The routine name can then be used as an argument in a parameter list as in 
the astadr argument of an AST-enabling routine. 
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The COMMON statement allows certain variables used in both program units (the 
main program and the subroutine) to share the same storage area © ®. You can use 
either the COMMON statement or the astprm argument in the AST-enabling routine 
to pass data to the AST routine. 

The virtual keyboard is created ® and bound to a display window O. 

In our program the AST-enabling routine that references the subroutine KEYSTRIKE 
® © is UIS$SET_KB_AST. Note that there is no separate call to the subroutine 
KEYSTRIKE. 

Whenever a key is struck, the ASCII character code for that character is stored 
in the variable keybuf © and subroutine KEYSTRIKE is executed. The subroutine 
KEYSTRIKE is an AST routine. 

The subroutine KEYSTRIKE retrieves the character code stored in the variable keybuf. 
The data structure TEXT, a character string descriptor, is created ©. The variable 
DESC denoting a record is defined to have the same structure as TEXT ®. The 
address of keybuf is assigned to a longword in the descriptor ®, The subroutine 
KEYSTRIKE writes the character to the virtual display using UIS$TEXT. 

After the AST routine completes execution, control returns to the next statement in 
the main program. The next statement is a call to the SYS$HIBER system service ©. 
The SYS$HIBER allows the process to remain inactive until the next time the AST 
routine is executed, that is, when a key is struck. 

The AST routine KEYSTRIKE also verifies that the virtual and physical keyboards are 
connected ®. 

Whenever column 60 is reached or the I return I key is pressed ®, text output moves 
to the next line. The ASCII character code for the I return I key is 13. 

17.2.4 Calling Keyboard Routines 

The program AST creates a viewport to which characters are written as shown in 
Figure 17-1. 
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Figure 17-1 Writing Characters to a Display Viewport 
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17.2.5 Using AST Routines with Pointer Devices 

Pointer routines allow the pointer to act as an input device to your application 
program. Typically, application programs use such data to keep track of the location 
of the pointer device in the virtual display, or the location of a specified rectangle in 
the virtual display. An effective way of using pointers in this manner is through AST 
routines. 

17.2.5.1 Mouse 

The mouse is a relative pointing device and can be used with AST routines to return 
status information about mouse location to the application. 

17.2.5.2 Tablet 

Another pointing device that you can use is the digitizer. The tablet consists of a 
puck or stylus and a tablet. Digitizer support may be used only with a tablet. 

Digitizing with a Tablet 

Digitizing with a tablet requires that you establish a region on the tablet—the data 
rectangle. The data rectangle is the area on the tablet in which digitizing is active. If 
you do not specify a data rectangle, the whole tablet is used. 

Only one data digitizing region may be active at one time. 

The pointer position on the tablet is available to the user's digitizing AST routine, 
if desired. If the pointer is within the data rectangle, then the user's AST routine is 
executed. 
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Only one image may own the tablet at any one time. When a process connects 
to the tablet, the system hardware cursor is turned off and the connected process 
receives all the input from the tablet device. The process must use a software cursor 
if it wishes to track the pointer in a window. The process owns the tablet until it 
makes a call to UIS$ENABLE_TB to disconnect itself from the tablet. 

Mouse Operation 

A mouse cannot be used as a data digitizer. The UIS routine will report an error, if 
you attempt to digitize with the mouse. 

Terminating Data Digitizing 

Only the process that issues the data digitizing request may change or cancel the 
request. If the process is deleted and the channel is deassigned, data digitizing is 
immediately canceled, if a request is still outstanding. 

Only one data digitizing region may be active at a time. Attempts by other processes 
to initiate will fail if another process has already declared a digitizing region. 

17.2.5.3 Step 1 —Create an AST Routine 

You must write a program that includes an AST subroutine that performs a task. 
Typically, AST subroutines perform inquiry functions and return pointer information 
such as location to the main program. See Table 12-1 for a list of pointer routines 
that return information about the pointer. You are not restricted to using AST 
routines in this manner. For example, you can use AST routines with pointers to 
create menus. 

17.2.5.4 Step 2 —Enable the AST Routine 

The AST routine will execute whenever a specific run-time event occurs. However, 
you must enable this behavior by including an AST-enabling routine in the main 
program. The following table lists pointer AST-enabling routines. 


Routine 

Run-Time Event 

UIS$SET_BUTTON_AST 

UIS$SET_TB_AST 

UIS$SET_POINTER_AST 

The button on the pointer device is depressed. 

The digitizer is moved within a specified data region on the 
tablet. 

The pointer is moved into a specified region of virtual display. 


17.2.6 Programming Options 

Many graphics applications use the pointer position and movement as a means of 
drawing objects on the display screen. Graphics routines can use this information to 
generate objects. 
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Pointer Movement 

Many application programs need to know where the pointer is. For example, the 
program might need to perform some type of action whenever the pointer moves 
within certain regions of the virtual display. The AST-enabling routine UIS$SET_ 
POINTER_AST can be used whenever pointer movement plays an important role in 
program execution. 

Pointer Position 

Your application may need to establish the position of the pointer in world 
coordinates. In addition, UIS$SET_POINTER_POSITION returns a status value. 

Pointer Pattern 

You can change the appearance of the pointer cursor using UIS$SET_POINTER_ 
PATTERN. Normally, this cursor appears as an arrow on the display screen. The 
pointer cursor, or pattern represents bit settings within an array of 16 words. You 
can choose your own pointer pattern by assigning a value to Qach word in the array 
that will set the desired bits for the new pattern. 

Optionally, you may request that the pointer also be bound to the region specified 
in the UIS$SET_POINTER_PATTERN call. When this region is unoccluded, the 
pointer pattern will not be allowed to exit after it has been positioned within the 
region. The cursor may leave the bound region, if it becomes occluded. 

Tablet Information 

Currently, two routines UIS$GET_TB_INFO and UIS$GET_TB_POSITION return 
information about tablet characteristics and position, respectively. 

17.2.7 Program Development 

Programming Objective 

To change the default pointer pattern to a crosshair. 

Programming Tasks 

1. Declare the subroutine and the appropriate variables in the COMMON statement. 

2. Create a virtual display. 

3. Create a display window and viewport. 

4. Enable pointer AST routine with UIS$SET_POINTER_AST. 
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5. Create a subroutine that defines the new cursor pattern. 

PROGRAM PATTERN 
IMPLICIT INTEGER(A-Z) 

EXTERNAL FIGURE O 

INCLUDE ’SYS$LIBRARY;UISENTRY’ 

INCLUDE ’SYS$LIBRARY;UISUSRDEF’ 

COMMON VD_ID.WD_ID 

VD_ID=UIS$CREATE_DISPLAY(-1.0,-1.0,30.0,30.0.20.0,20.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’.’POINTER PATTERN’) Q 

CALL UIS$SET_POINTER_AST(VD_ID,WD_ID.FIGURE.0) ® 

CALL SYS$HIBER() 

END 

SUBROUTINE FIGURE 
IMPLICIT INTEGER(A-Z) 

INTEGER*2 CURSOR(16) O 
INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

COMMON VD_ID.WD_ID 

DATA CURS0R/7*896.65535,8*896/ ® 

CALL UIS$SET_POINTER_PATTERN(VD_ID.WD_ID.CURSOR,,8.8) O 

RETURN 

END 

In this program, no world coordinates are specified for the display window ©, so the 
display window maps the entire virtual display space. The dimensions of the display 
viewport are also not specified. As a result, the display viewport size defaults to the 
dimensions specified in UIS$CREATE—DISPLAY. 

The subroutine FIGURE is called whenever the pointer lies within the specified 
area of the display window. In the main program the subroutine is declared as an 
external procedure O in the main program. The AST-enabling routine for the pointer 
devices UIS$SET_POINTER_AST is called ©. Because no rectangle is specified, the 
subroutine FIGURE is executed whenever the pointer is within the display window. 

The array CURSOR is declared in the subroutine FIGURE O and contains 16 
elements. Each array element is declared as a word and is, therefore, 16 bits 
long. You should imagine the array as a 16 by 16-bit pattern, or matrix. Each 
array element ® is assigned a value which sets certain bits in the matrix to 1 . The 
matrix represents the bitmap image of the new cursor pattern. The call to UIS$SET— 
POINTER-PATTERN references the new cursor pattern and the exact bit in the new 
cursor pattern used to calculate current pointer position ®. 



17-12 Asynchronous System Trap Routines 


17.2.8 Calling UIS$SET-POINTER_AST and 
UIS$SET^POINTER_PATTERN 

When you run the program PATTERN, the display viewport is created. The pointer 
lies outside thfe display viewport and the default pointer pattern is in effect as shown 
in Figure 17-2. 

Figure 17-2 Default Pointer Pattern 



The process executing the main program is hibernating, that is, waiting for you to 
move the pointer. As you can see in Figure 17-3, when you move the pointer within 
the display window, the pointer pattern changes from an arrow to a cross. 
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Figure 17-3 New Pointer Pattern 



17.3 Manipulating Display Windows and Viewports 

Default Shrinking Operation 

The shrinking of viewports is performed using the Window Options Menu by default. 
When you choose the "Shrink to an Icon" menu item, UIS$SHRINK_TO_ICON is 
called. You can also expand icons to viewports with the user interface by placing the 
cursor in the icon and pressing the pointer button. 

Default Resizing and Closing Operations 

Resizing and closing display windows are performed using the Window Options 
Menu by default. When you choose the "Change the size" menu item, UIS$RESIZE_ 
WINDOW is called and accepts the world coordinate values of the newly resized 
window. 

Display windows are also closed using the Window Options Menu. When you 
choose the "Delete" menu item, UIS$CLOSE—WINDOW is called, which, in turn, 
calls SYS$EXIT system service. SYS$EXIT performs image rundown and deletes the 
process that owns the image. 
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17.3.1 Using AST Routines to Modify the Window Options Menu 

Certain UIS routines can override the default actions listed in the Window Options 
Menu and enable user-written shrinking, expanding, resizing and closing AST 
routines that are activated whenever the "Shrink to an Icon", "Change the size", 
or "Delete" menu items are chosen. In this case, AST routines override the default 
shrinking, expansion, resizing, and closing UIS behavior. 

17.3.1.1 Step 1—Create an AST Routine 

In order to override one of the default actions listed in the Window Options Menu, 
you must write a program that includes an AST routine. When you execute the 
program and initiate the action through the user interface, the default action is no 
longer performed automatically. 

You could code your AST routine so that it could perform any action. Most likely, 
you will modify the action of a menu item by adding additional actions to the default. 
If so, you must include in your AST routine a call to UIS$RESIZE—WINDOW in 
addition to code to perform any other special features you see fit. When the program 
executes, the AST routine will perform the resize as well as any other additional 
actions. The following table lists the task you wish to perform and the corresponding 
UIS routine that should be included in your subroutine. 


Task 

Routine 

Close or delete a window 

UIS$CLOSE -WINDOW 

Expand an icon^ 

UIS$EXPAND_ICON 

Resize a viewport 

UIS$RESIZE -WINDOW 

Shrink a viewport 

UIS$SHRINK_TO_ICON 


Not listed in the Window Options Menu. 


17.3.1.2 Step 2—Enable the AST Routine 

You want your AST routine to execute whenever you wish to override the default 
features listed in the Window Options Menu. In order to execute the AST routine, a 
run-time event must occur to trigger the AST routine. Therefore, you must include 
in your main program an appropriate AST-enabling routine. The following table 
lists window AST-enabling routines that trigger AST routine execution for various 
run-time events. 
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Routine 

Run-Time Event 

UIS$SET_CLOSE_AST 

The "Delete" menu item is chosen using the user 
interface. 

UIS$SET_EXPAND_ICON_AST 

The pointer pattern is placed on an icon and the 
pointer button is depressed. 

UIS$SET_RESIZE _WINDOW_AST 

The "Change the size" menu item is chosen using 
the user interface 

UIS$SET_SHRINK_TO_ICON_AST 

The "Shrink to an icon" menu item is chosen using 
the user interface. 


17.3.2 Programming Options 

You can enable AST routine execution for the programming options listed below. 

Shrinking Viewports to Icons 

You can override the default display viewport shrinking operation by first calling the 
AST-enabling routine UIS$SET_SHRINK_TO_ICON_AST in your main program. 
Your AST routine will contain UIS$SHRINK_TO_ICON specifying icon attributes. 
Shrinking viewports to icons occurs as a five-step as follows: 

1. The user initiates the shrinking operation using the user interface. 

2. The viewport is moved offscreen using the invisible attribute. 

3. The subroutine creates a small virtual display and viewport with no banner, the 
actual icon. 

4. The subroutine using UIS$SHRINK_TO_ICON associates the icon name with 
the virtual display identifier of the offscreen viewport. 

Expanding Icons to Display Viewports 

You can override the default icon expansion operation by calling the AST- 
enabling routine UIS$SET__EXPAND_ICON_AST in your main program. Include 
UIS$EXPAND_ICON in your AST routine in order to specify viewport attributes. 

Resizing Display Windows 

You can override the default display window resize operation by first calling the 
AST-enabling routine UIS$SET_RESIZE_AST in your main program. Resizing 
occurs as a three-step process as follows: 

1. The user initiates the resizing operation using the user interface. 

2. The user interface returns values to the addresses specified in 
UIS$SET_RESIZE_AST. 
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3. The AST routine is called. 

Your AST routine will include a call to UIS$RESIZE—WINDOW. A call to 
UIS$RESIZE—WINDOW can redefine the default resize behavior in the following 
ways: 

• Absolute position — You can specify an absolute position, that is, a device 
coordinate position on the physical screen where the newly resized display 
viewport will be placed. 

• Size — You can specify the dimensions of all newly resized display viewports. 
All subsequent display viewports are created with these dimensions. 

• World coordinate space — You can specify the world coordinate space as the 
original display window. Typically, the coordinates that you specify here match 
the world coordinates of the original display window. However, this need not 
always be the case. If your original display window viewed a portion of the 
virtual display, you can view more or less of the virtual display depending on 
the world coordinate range you specify. 

Closing Display Windows 

To override the default close display window operation, you must first call the 
AST-enabling routine UIS$SET_CLOSE_AST in your main program. 

The instructions that you include in your AST routine will override the default 
window closing behavior. Closing display windows occurs as a two-step process as 
follows: 

1. The "Delete" menu item in the Window Option menu is chosen. 

2. The AST routine is called. 

17.3.3 Program Development 

Programming Objective 

To modify the display window shrinking, expanding, resizing, and closing operations 
listed in the Window Options Menu, whenever the "Shrink to icon", "Change the 
size" or "Delete" menu item is chosen. 

Programming Tasks 

1. Declare the subroutines and the appropriate variables in the COMMON 
statement. 

2. Create a virtual display. 

3. Create a display window and viewport. 

4. Draw two ellipses and a circle. 
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5. Enable viewport shrinking and icon expansion AST routines using UIS$SET_ 
SHRINK_TO_ICON_AST and UIS$SET_EXPAND_ICON_AST. 

6. Enable window resizing and closing AST routines using U1S$SET_RESIZE_AST 
UIS$SET_CLOSE_AST. 

7. Create viewport shrinking and icon expansion AST routines. 

8. Create window resizing and closing AST routines. 

PROGRAM OVERRIDE 
IMPLICIT INTEGER(A-Z) 

EXTERNAL RESIZER,SHRINKER.EXPANDER,CLOSER 
INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

COMMON VD_ID.VD_ID2,WD_Id,WD_ID2,NEW_ABS_X.NEW_ABS_Y 

VD_ID=UIS$CREATE_DISPLAY(0.0.0.0.50.0.50.0,10.0,10.0) O 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$WORKSTATION’,’USER’) Q 

CALL UISSELLIPSE(VD_ID.0.10.0.20.0.5.0,15.0) 

CALL UIS$SET_FONT(VD_ID,0.1.’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD_ID.1.1,PATT$C_VERT6_2) 

CALL UIS$CIRCLE(VD_ID.1,25.0.25.0.20.0) 

CALL UIS$ELLIPSE(VD_ID.0.40.0.20.0,5.0,15.0) 

CALL UIS$SET_SHRINK_TO_ICON_AST(WD_ID.SHRINKER) O 
CALL UIS$SET_EXPAND_ICON_AST(WD_ID.EXPANDER) © 

CALL UIS$SET_CLOSE_AST(WD_ID.CLOSER.0) © 

CALL UIS$SET_RESIZE_AST(VD_ID.WD_ID,RESIZER,0.NEW_ABS_X,NEW_ABS_Y. 
2 NEW.WIDTH.NEW_HEIGHT.NEW_WC_X1.NEW_WC_Y1,NEW_WC_X2. 

2 NEW_WC_Y2) ® 

CALL SYS$HIBER() O 

TYPE *.’DISPLAY WINDOW HAS BEEN SUCCESSFULLY CLOSED’ O 
END 

SUBROUTINE RESIZER © 

IMPLICIT INTEGER(A-Z) 

COMMON VD_ID.VD_ID2,WD_ID,wd_id2,NEW_ABS_X.NEW_ABS_Y 

CALL UIS$RESIZE_WINDOW(VD_ID,WD_ID,NEW_ABS_X.NEW_ABS_Y..) © 

RETURN 

END 
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SUBROUTINE SHRINKER ® 

IMPLICIT INTEGER(A-Z) 

INCLUDE ’SYS$LIBRARY:UISENTRY’ 

INCLUDE ’SYS$LIBRARY:UISUSRDEF’ 

COMMON VD_ID.VD_ID2.WD_ID.WD_ID2.NEW_ABS_X.NEW_ABS_Y 

STRUCTURE/AWAY/ ® 

INTEGER+4 CODEl 
INTEGER*4 ATTRl 
INTEGER+4 C0DE2 
INTEGER*4 ATTR2 
INTEGER+4 END.LIST 
END STRUCTURE 

RECORD/AWAY/WINDOW ® 

WINDOW.C0DE1=WDPL$C_PLACEMENT ® 

WINDOW.ATTR1=WDPL$M_INVISIBLE ® 

WINDOW.C0DE2=WDPL$C_END_0F_LIST © 

CALL UIS$MOVE_VIEWPORT(WD_ID.WINDOW) © 

WINDOW.CODEl=WDPL$C_ATTRIBUTES © 

WINDOW.ATTR1=WDPL$M_N0BANNER © 

WINDOW.C0DE2=WDPL$C_END_0F_LIST © 

VD_ID2=UIS$CREATE_DISPLAY(0.0,0.0.5.0,5.0,2.54,2.54) © 

WD_ID2=UIS$CREATE_WIND0W(VD_ID2,’SYS$WORKSTATION’,, 


2 .,....WINDOW) © 

CALL UIS$SET_FONT(VD_ID2,0.2,’MY_F0NT_5’) 

CALL UISlTEXT(VD_ID2.2.’USER’,0.5,3.5) © 

ICON_FLAGS=UIS$M_ICON_DEF_BODY © 

CALL UIS$SHRINK_TO_ICON(WD_ID.WD_ID2.ICON.FLAGS) © 


RETURN 

END 

SUBROUTINE EXPANDER 
IMPLICIT INTEGER(A-Z) 

COMMON VD_ID.VD_ID2,WD_ID,WD_ID2.NEW_ABS_X.NEW_ABS_Y 

CALL UIS$EXPAND_ICON(WD_ID,WD_ID2) 

RETURN 

END 

SUBROUTINE CLOSER © 

IMPLICIT INTEGER(A-Z) 

COMMON VD_ID.VD_ID2,WD_ID.WD_ID2.NEW_ABS_X,NEW_ABS_Y 
CALL UIS$ERASE(VD_ID) 

CALL UIS$DELETE_WINDOW(WD_ID) © 
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CALL UIS$DELETE_DISPLAY(VD_ID) © 

CALL SYS$WAKE(,) © 

RETURN 

END 

The main program OVERRIDE creates a virtual display O and a display window 
The world coordinate space of the display window is a portion of the virtual display, 
the display window contains only those objects in the virtual display that lie 
within it. 

A circle is drawn between two ellipses in the virtual display and appears in the 
display window and its associated display viewport. 

Four AST-enabling routines, UIS$SET_SHRINK_TO_ICON_AST, UIS$SET_ 
EXPAND_ICON_AST, UIS$SET_CLOSE_AST and UIS$SET_RESIZE_AST, © 

O 0 © are called. The main program executes until the call to SYS$HIBER is 
reached O. 

The Window Options Menu is invoked from the MENU icon in the viewport 
WINDOW using the pointer. Assume that the menu item "Change the size" is 
chosen. Perform the following procedure; 

1. Move the pointer to one of the flashing dots on the border of the viewport. 

2. Press the button and the border of the display viewport is highlighted. 

3. Hold the button down and move the pointer until the stretchy box is the desired 
size and release the pointer button. 

The call to UIS$RESIZE—WINDOW © in the subroutine RESIZER 0 modifies the 
default resize behavior. UIS$RESIZE—WINDOW specifies the world coordinates of 
the existing virtual display as the world coordinates for all newly resized display 
windows. Therefore, a newly resized window always displays the entire virtual 
display space. If the aspect ratios of the virtual display and the resized display 
viewport are not equal, graphic objects are scaled. 

The subroutine SHRINKER 0 modifies the default shrinking behavior. The window 
attributes data structure AWAY is created 0. A record WINDOW is defined to have 
the structure of AWAY ®. The fields of record WINDOW are assigned values © 

® ©. Note the use of the invisible placement attribute. A call to UIS$MOVE— 
VIEWPORT ® references the display window identifier of the existing viewport and 
the current window attributes. The viewport is moved offscreen. 

New window attribute values are assigned © © © to the fields of the record 
WINDOW. 
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A virtual display and display window are created for the icon ® ®. UIS$TEXT 
draws the character string in the icon The flag UIS$M_ICON_DEF_BODY sets 
the appropriate in the mask icon_flags ©, When this bit is set, the area of the icon 
becomes a button AST region (for later icon expansion). UIS$SHRINK_TO_ICON 
© associates the display window identifiers of the existing viewport and the icon. 

The subroutine CLOSER © overrides the default window closing behavior by 
deleting the display window ®, display viewport, and the virtual display ©. The 
process that owns the main program is awakened ©. The main program continues 
execution with the next statement after the call to SYS$HIBER ®, types the message 
"Display window has been successfully closed", and terminates. 

17.3.4 Calling UIS$SET_RESIZE^ST 

When the main program executes, a display window and its associated display 
viewport appear on the display screen as shown in Figure 17-4. 

Figure 17-4 Unresized Window and Viewport 



The menu item "Change the size" is selected and the display window and viewport 
are resized as shown in Figure 17-5. 
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Figure 17-5 Resized Window and Viewport 
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17.3.5 Calling UIS$SET__SHRINK_TO_ICON_JVST 

The menu item "Shrink to icon" is selected and the display viewport is replaced with 
a user-defined icon as shown in Figure 17-6. 

Figure 17-6 Icon 



ZK-5484-86 
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17.3.6 Calling UIS$SET_CLOSE_AST 

When the menu item "Delete" is chosen, the display viewport, window, and virtual 
display are deleted and the message "Display window has been successfully closed" 
is written to the terminal emulation window. 



PART III UlS Routines 





Chapter 18 

UlS Routine Descriptions 

18.1 Overview 

Each UIS and UISDC routine in Parts III and IV of this book is documented using 
a structured format. This section discusses the main headings of this format, the 
information that is presented under each heading, and the format used to present the 
information. 

The purpose of this section, therefore, is to explain where to find information and 
how to read it correctly, not how to use it. 

Some main headings in the routine template contain information that requires no 
further explanation beyond what is given in Table 18-1. However, the following 
main headings contain information that does require additional discussion; this 
discussion takes place in the remaining subsections of this section. 

• Format Heading 

• Returns Heading 

• Arguments Heading 

The following table lists the main headings in the UIS routines template. 

Table 18-1 Main Headings in the Routine Template 
Main Heading Description 

Routine Name Required. The routine entry point name is usually, though not 

always, followed by the English name of the routine. 

Routine Overview Required. The routine overview appears directly below the routine 

name; the overview explains, usually in one or two sentences, 
what the routine does. 
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Table 18-1 (Cont.) Main Headings in the Routine Template 
Main Heading Description 


Format 


Returns 

Arguments 


Description 


Examples 


Required. The format heading follows the routine overview. 

The format gives the routine entry point name and the routine 
argument list. 

Required. The returns heading follows the routine format. It 
explains what information is returned by the routine. 

Required. The arguments heading follows the returns heading. 
Detailed information about each argument is provided under the 
arguments heading. If a routine takes no arguments, the word 
"None" appears. 

Optional. The description heading follows the arguments heading] 
The description section contains information about specific actions 
taken by the routine: interaction between routine arguments, if 
any; operation of the routine within the context of VAX/VMS; 
user privileges needed to call the routine, if any; system resources 
used by the routine; and user quotas that may affect the operation 
of the routine. 

Note that any restrictions on the use of the routine are always 
discussed first in the description section; for example, any required 
user privileges or necessary system resources are explained first. 

For some simple routines, a description section is not necessary 
because the routine overview carries the needed information. 

Optional. The examples heading appears following the description 
heading. The examples section contains programming examples 
that illustrate use of the routine. Following the example, an 
explanation of the example is given. 

All examples have been tested and should run when compiled (or 
assembled) and linked. 
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Table 18-1 (Cont.) 

Main Headings in the Routine Template 

Main Heading 

Description 

Screen Output 

Optional. The screen output heading contains either an actual 
display produced by the routine or information that the routine 
would normally return to the program. Please note that in many 
instances screen output contains annotations that serve only 
to explain the information returned. For example, UIS$GET_ 
POSITION returns information about the current text position 
along the actual path. This information is displayed and described 
as an example of the kind of data that can be returned. In many 
cases such as the inquiry routines, the displayed information is 
formatted with headings and annotations for the purposes of 
presentation in this manual only. 

Illustration 

Optional. The illustration heading contains artwork that describes 
how to use the routine, how the routine functions, or what kind 
of information to expect from it. The illustrations may or may not 
be annotated. 


18.1.1 Format Heading 

The following types of information can be present in the format heading. 

• Procedure call format 

• Explanatory text 

The procedure call format ensures that a routine call conforms to the procedure 
call mechanism described in the VAX Procedure Calling and Condition Handling 
Standard; for example, an entry mask is created, registers are saved, and so on. 

Procedure call formats can appear in many forms. Four examples have been provided 
to illustrate the meaning of syntactical elements such as brackets and commas. 
General rules of syntax governing how to use procedure call formats are shown in 
Table 18-2. 

Example 1 This example illustrates the standard representation of optional 
arguments and best describes the use of commas as delimiters. Arguments enclosed 
within square brackets are optional, but if an optional argument other than a trailing 
optional argument is omitted, you must include a comma as a delimiter for the 
omitted argument. 

ENTRY-POINT-NAME argl [,[arg2 [,arg3]] 

Typically, VAX RMS system routines use this format where at most three arguments 
appear in the argument list. 
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Example 2 When the argument list contains three or more optional arguments, the 
syntax does not provide enough information. If the optional arguments arg3 and 
arg4 are omitted and the trailing argument argS is specified, commas must be used 
to delimit the positions of the omitted arguments. 

ENTRY-POINT-NAME argl ,arg2 ,[argS] ,nullarg [,arg4] [,arg5] 

Typically, VAX/VMS system services, utility routines, and VAX Run-Time Library 
routines contain call formats with more than three arguments. 

Example 3 In the following call format example, the trailing four arguments are 
optional as a group, that is, either you specify arg2, arg3, arg4, and argS or none of 
them. Therefore, if the optional arguments are not specified, commas need not be 
used to delimit unoccupied positions. 

However, if a hypothetical required argument or a separate optional argument were 
specified after argS, commas must be used when arg2, arg3, arg4, and argS are 
omitted. 

ENTRY-POINT-NAME argl [,arg2 .arg3 ,arg4 .arg5] 

Example 4 In the following example, you may specify arg2 and omit arg3. 
However whenever you specify arg3, you must specify arg2 
ENTRY-POINT-NAME argl [.arg2 [.arg3]] 

Explanatory Text 

Explanatory text may follow one or both of the above formats. This text is present 
only when needed to clarify the format. For example, the call format indicates that 
arguments are optional by enclosing them in brackets ([]). However, brackets alone 
cannot convey all the important information that may apply to optional arguments. 
For example, in some routines that have many optional arguments, if one optional 
argument is selected, another optional argument must also be selected. In such cases, 
text following the format clarifies this fact. 


Table 18-2 General Rules of Syntax 


Element 

Entry point names 
Argument names 
Spaces 

Braces 

Brackets ([ ]) 


Syntax Rule 

Entry point names are always shown in uppercase characters. 
Argument names are always shown in lowercase characters. 

One or more spaces are used between the entry point name 
and the first argument, and between each argument. 

Braces surround two or more arguments. You must choose 
one of the arguments. 

Brackets surround optional arguments. Note that commas too 
can be optional (see the comma element). 
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Table 18-2 (Cont.) 

General Rules of Syntax 

Element 

Syntax Rule 

Commas 

Between arguments, the comma always follows the space. If 
the argument is optional, the comma may appear inside the 
brackets or outside the brackets, depending on the position 
of the argument in the list and on whether surrounding 
arguments are optional or required. 

Null arguments 

A null argument is a place-holding argument. It is used 
for either of the following reasons: {1) to hold a place in 
the argument list for an argument that has not yet been 
implemented by DIGITAL but may be in the future or (2) 
to mark the position of an argument that was used in earlier 
versions of the routine but is not used in the latest version 


(upward compatibility is thereby ensured because arguments 
that follow the null argument in the argument list keep their 
original positions). A null argument is always given the name 

nullarg. 


In the argument list constructed on the stack when a 
procedure is called, both null arguments and omitted optional 
arguments are represented by longword argument list entries 
containing the value 0. The programming language syntax 
required to produce argument list entries containing 0 differ 
from language to language, so see your language user's guide 
for language-specific syntax. 


18.1.2 Returns Heading 

Under the returns heading appears information that describes what information, 
if any, is returned by the routine to the caller. Programs written in VAX MACRO 
return information in RO. The information that is returned is a longword value. 

The high-level language programmer receives status information in the return (or 
status) variable he or she uses when making the call. The run-time environment 
established for the high-level language program allows the status information in 
RO to be moved automatically to the user's return variable. The information that is 
returned is always a longword value. 
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18.1.3 Arguments Heading 

Under the arguments heading appears detailed information about each argument 
listed in the call format. Arguments are described in the order in which they appear 
in the call format. If the routine has no arguments, the term "none" appears. 

The following format is used to describe each argument, 

argument-name 


VMS Usage; 
type: 
access: 
mechanism: 


argument-VMS-data-type 

argument-data-type 

argument-access 

argument-passing-mechanism 


One paragraph of structured text, followed by other 
paragraphs of text, as needed. 


18.2 Functional Organization of UlS Routines 

The UIS routines perform many functions within an application program. Besides, 
creating the graphic objects that you see on the display screen, there are routines 
that manage the input devices and routines that return information to the program to 
name a few. 

Figure 18-1 lists each UIS routine by functional category. 
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Figure 18-1 Functional Categories of UIS Routines 


AST-Enabling Routines 

UIS$SET_ADDOPT_AST 

UIS$SET_BUTTON_AST 

UIS$SET_CLOSE_AST 

UIS$SET_EXPAND_ICON_AST 

UIS$SET_GAIN_KB_AST 

UIS$SET_KB_AST 

UIS$SET_LOSE _KB_AST 

UIS$SET_MO VE _INFO_AST 

UIS$SET_POINTER_AST 

UIS$SET_RESIZE_AST 

UIS$SET_SHRINK_TO_ICON_AST 

UIS$SET_TB_AST 

Attribute Routines 

UIS$SET_ARC_TYPE 

UIS$SET_BACKGROUND_INDEX 

UIS$SET_CHAR_ROTATION 

UIS$SET_CHAR_SIZE 

UIS$SET_CHAR_SLANT 

UIS$SET_CHAR_SPACING 

UIS$SET_CLIP 

UIS$SET_FILL -PATTERN 

UIS$SET_FONT 

UIS$SET_LINE -STYLE 

UIS$SET-LINE-WIDTH 

UIS$SET-TEXT-FORMATTING 

UIS$SET-TEXT_MARGINS 

UIS$SET-TEXT-PATH 

UIS$SET-TEXT-SLOPE 

UIS$SET-WRITING-INDEX 

UIS$SET-WRITING-MODE 

Color Routines 

UIS$CRE ATE -COLOR -MAP 

UIS$CREATE-COLOR-MAP-SEG 

UISSDELETE -COLOR -MAP 

UIS$DELETE-COLOR_MAP-SEG 

UIS$HLS_TO-RGB 

UIS$HSV-TO-RGB 

UISSRESTORE -CMS-COLORS 

UIS$RGB-TO-HLS 

UIS$RGB-TO-HSV 

UIS$SET-COLOR 

UIS$SET-COLORS 

UISSSET-INTENSITIES 

UISSSET-INTENSITY 


Display List Routines 

UISSBEGIN-SEGMENT 

UISSCOPY-OBJECT 

UISSDELETE-OBJECT 

UISSDELETE-PRIVATE 

UISSDIS ABLE -DISPLAY-LIST 

UISSEN ABLE-DISPLAY-LIST 

UISSEND-SEGMENT 

UIS$ERASE 

UIS$EXECUTE 

UISSEXECUTE-DISPLAY 

UISSEXTRACT-HEADER 

UIS$EXTRACT-OBJECT 

UISSEXTRACT-PRIVATE 

UIS$EXTRACT_REGION 

UIS$EXTRACT-TRAILER 

UISSFIND-PRIMITIVE 

UIS$FIND-SEGMENT 

UIS$INSERT_OBJECT 

UIS$MOVE-AREA 

UISSPRIVATE 

UISSSET-INSERTION-POSITION 

UISITRANSFORM-OBJECT 

Graphics Routines 

UISSCIRCLE 

UISSELLIPSE 

UIS$IMAGE 

UISSLINE 

UIS$LINE-ARRAY 

UIS$PLOT 

UIS$PLOT-ARRAY 

Inquiry Routines 

UIS$GET-ABS-POINTER-POS 

UISSGET-ALIGNED-POSITION 

UIS$GET-ARC-TYPE 

UIS$GET-BACKGROUND_INDEX 

UISSGET-BUTTONS 

UIS$GET-CH AR -ROTATION 

UIS$GET-CHAR_SIZE 

UIS$GET-CHAR-SLANT 

UIS$GET-CHAR-SPACING 

UIS$GET-CLIP 

UIS$GET-COLOR 

UIS$GET-COLORS 

UIS$GET-CURRENT-OBJECT 

ZK 4674-85 


(Continued on next page) 
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Figure 18-1 (Cont.) Functional Categories of UIS Routines 


Inquiry Routines (cont.) 

UIS$GET_DISPLAY_SIZE 

UIS$GET_FILL _PATTERN 

UIS$GET_FONT 

UIS$GET_FONT_ATTRIBUTES 

UIS$GET_FONT_SIZE 

UIS$GET_HW_COLOR_INFO 

UIS$GET_INTENSITIES 

UIS$GET_INTENSITY 

UIS$GET_KB_ATTRIBUTES 

UIS$GET_LINE _ST YLE 

UIS$GET_LINE _WIDTH 

UIS$GET_NEXT_OBJECT 

UIS$GET_OBJECT_ATTRIBUTES 

UIS$GET_PARENT_SEGMENT 

UIS$GET_POINTER_POSITION 

UIS$GET_POSITION 

UIS$GET_PREVIOUS_OBJECT 

UIS$GET_ROOT_SEGMENT 

UIS$GET_TB_INFO 

UIS$GET_TB_POSITION 

UIS$GET_TEXT_FORMATTING 

UIS$GET_TEXT_MARGINS 

UIS$GET_TEXT_PATH 

UIS$GET_TEXT_SLOPE 

UIS$GET_VCM_ID 

UIS$GET_VIEWPORT_ICON 

UIS$GET_VIEWPORT_POSITION 

UIS$GET_VIEWPORT_SIZE 

UIS$GET_VISIBILITY 

UIS$GET_WINDOW_ATTRIBUTES 

UIS$GET_WINDOW_SIZE 

UIS$GET_WRITING_INDEX 

UIS$GET_WRITING_MODE 

UIS$GET_WS_COLOR 

UIS$GET_WS_INTENSITY 

Keyboard Routines 

UIS$CREATE_KB 

UIS$DELETE_KB 

UIS$DISABLE_KB 

UIS$DISABLE_VIEWPORT_KB 

UIS$ENABLE_KB 

UIS$EN ABLE _VIEWPORT_KB 


Keyboard Routines (cont.) 

UIS$READ_CHAR 

UIS$SET_KB_ATTRIBUTES 

UIS$SET_KB_COMPOSE2 

UlS$SET_KB_COMPOSE3 

UIS$SET_KB_KEYTABLE 

UIS$TEST_KB 


Pointer Routines 

UIS$CREATE_TB 

UIS$DELETE_TB 

UIS$DISABLE_TB 

UIS$ENABLE_TB 

UIS$SET_POINTER_PATTERN 

UIS$SET_POINTER_POSITION 

Sound Routines 

UIS$SOUND_BELL 

UIS$SOUND_CLICK 

Text Routines 

UIS$MEASURE_TEXT 

UIS$NEW_TEXT_LINE 

UIS$SET_ALIGNED_POSITION 

UISSSET-POSITION 

UIS$TEXT 

Windowing Routines 

UIS$CLOSE _WINDO W 

UISSCRE ATE -DISPLAY 

UISSCRE ATE -TERMINAL 

UISSCREATE-TRANSFORMATION 

UIS$CRE ATE-WINDOW 

UISSDELETE-DISPLAY 

UISSDELETE-TRANSFORMATION 

UISSDELETE-WINDOW 

UIS$EXPAND-ICON 

UIS$MOVE-VIEWPORT 

UIS$MOVE -WINDOW 

UIS$POP-VIEWPORT 

UIS$PUSH_VIEWPORT 

UISSRESIZE-WINDOW 

UIS$SHRINK-TO-ICON 
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UIS$BEGIN_SEGMENT 


UIS$BEGIN^SEGMENT 


Begins a new segment in the virtual display. 


Format 

sefif_/cy=UIS$BEGIN_SEGMENT vdUd 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the segment identifier in the variable seg—id or 
RO (VAX MACRO). The segment identifier uniquely identifies a segment and 
is used as an argument in other routines. 

UIS$BEGIN_SEGMENT signals all errors; no condition values are returned. 


Argument 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


Description 

All values of attribute blocks 0 to 255 are propagated to the new segment, 
but all changes to attribute blocks in this segment will be local to this 
segment only and not the parent. 

You can also nest segments. 
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Illustration 

First-Level Segment 

U1S$BEGIN_SEGMENT - 

Second-Level Segment 
UIS$BEGIN_SEGMENT - 


UIS$END_SEGMENT - 

Second-Level Segment 

UIS$BEGIN_SEGMENT - 

Third-Level Segment 

UIS$BEGIN_SEGMENT - 

UIS$END_SEGMENT - 

UIS$END_SEGMENT - 


UIS$END_SEGMENT 


ZK-5371-86 
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UIS$CIRCLE 

Draws an arc along the circumference of a circle. 

Format 

UIS$CIRCLE vd—id, atb, center—x, center—y, xradius 
[,start—deg,end—deg] 

Returns 

U1S$CIRCLE signals all errors; no condition values are returned. 

Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 

atb 

VMS Usage: iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a Iongword 
integer that specifies an attribute block that controls the appearance of the 
circle or arc. 

center—X, center—y 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Center position x and y world coordinates. The center— x and center— y 
arguments are the addresses of f—floating point numbers that define a point 
in the virtual display that is the center of the arc or circle. 
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xradius 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Radius of the circle specified as an x world coordinate width. The xradius 
argument is the address of an f—floating point number that defines the 
distance from the center of the circle to the circumference of the circle. 

Start—deg, end—deg 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Degree at which the arc starts and ends. The start-deg and end—deg 
arguments are the addresses of f—floating point numbers that define the 
starting and ending point on the circumference of the circle where the arc 
or circle will be drawn. Degrees are measured clockwise from the top of the 
circle. If these arguments are not specified, 0.0 degrees and 360.0 degrees are 
assumed, respectively. 


Description 

UIS$CIRCLE draws an arc specified by a center position and a radius for the 
range of the degrees specified. 

The arc can be closed by drawing one or more lines between the endpoints. 
The arc type associated with the attribute block specifies the way in which 
the arc is closed. The arc is not closed off by default. See UIS$SET—ARC- 
TYPE for details. 

The points are drawn with the current line pattern and width, and filled with 
the current fill pattern if enabled. 

UIS$CIRCLE does not support the following combination of attributes: 

• Line width not equal to 1 and line style not equal to FFFFFFFFk, 

• Line width not equal to 1 and complement writing mode 

Circles are distorted by differences between the aspect ratios of the display 
window and display viewport. 
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UIS$CLOSE_WINDOW 


Calls the system service SYS$EXIT to exit the current image. 


Format 

UIS$CLOSE_WINDOW wd-id 


Returns 

UIS$CLOSE—WINDOW signals all errors; no condition values are returned. 


Argument 


wd—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 


Description 

UIS$CLOSE—WINDOW is invoked as the default action taken by the 
"Delete" menu item in the Window Options Menu. See UIS$SET—CLOSE— 
AST for information about overriding this routine. 
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UIS$COPY_OBJECT 


UIS$COPY_OBJECT 

Copies the specified object and its private data within the virtual display. 
It may also transform the coordinates or attributes or both of the specified 
object. The original object remains unchanged in the virtual display. 


Format 

copy_/Gf=UIS$COPY_OBJECT 




Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the copy identifier in the variable copy—id or RO 
(VAX MACRO). The copy identifier uniquely identifies a newly copied object. 

UIS$COPY_OBJECT signals all errors; no condition values are returned. 


Arguments 


obi—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Object identifier. The obj_id argument is the address of a longword that 
uniquely identifies an object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg_id argument is the address of a longword that 
uniquely identifies the segment. See UIS$BEG1N—SEGMENT for more 
information about the seg_id argument. 
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matrix 


VMS Usage; 
type: 
access; 
mechanism: 


vector—longword—signed 
f—floating 
read only 
by reference 


Transformation matrix. The matrix argument is the address of a 2 x 3 matrix 
of longwords containing scaling, translation, and/or rotation data. 


Structure of a VAX FORTRAN Two-Dimensional Array 

A two-dimensional array declared as ARRAY(2,3) has the following structure. 


1,1 

1,2 

1,3 

2,1 

2,2 

2,3 


ZK-5492-86 


Different languages allocate memory for array elements in different orders. 
This description assumes the order used by VAX FORTRAN. If you call 
UIS$COPY_OBJECT from another language, make sure that the array 
elements are in the same order. 

Memory addresses of array elements range from lowest to highest in the 
following order; (1,1),(2,1), (1,2),(2,2),(1,3), and (2,3). The order of array 
element is shown in the following figure. 


1 

3 

5 

2 

4 

6 


ZK-5493-86 


Pairs of array elements govern how displayed objects are scaled, rotated, 
and translated. UIS computes the transformed coordinates in the following 
manner. 

Xi = A(l,l)*x + A(l,2)*y + A(l,3) 

Yl = A(2,l)*x + A(2,2)*y + A(2,3) 
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Translation 

When translation alone is performed, the following array elements are 
assigned values. Dx and Dy represent distances between the original 
coordinates and the new coordinates. 


1 

0 

Dx 

0 

1 

Dy 


ZK-5494-86 


Scaling 

When scaling alone is performed, the following array elements are assigned 
values. 


Sx 

0 

0 

0 

Sy 

0 


ZK-5495-86 


Rotation 

When rotation alone is performed, the following array elements are assigned 
values, where is the desired angle of rotation measured clockwise. The 
values returned from the VAX FORTRAN SIN and COS functions are stored 
in the appropriate array elements. 


cos (@) 

sin ((§)) 

0 

-sin (@) 

cos (@) 

0 


ZK-5496-86 


An unlimited number of transformations can be performed at one time by 
simply multiplying the matrices together into a single matrix using matrix 
multiplication. 
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In order to multiply two matrices together, you must add a row to the bottom 
of each matrix. 
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After the multiplication is performed, remove the last row of the result. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block whose attribute settings override current segment 
attributes. 


Description 

Either the coordinates can be transformed, or the attributes can be overridden 
or both. 

After a transformation, occluded objects may not appear correctly on the 
display screen. This can be corrected by calling UIS$EXECUTE to correctly 
refresh the display screen. 
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UIS$CREATE_COLOR^MAP 

Creates a virtual color map of the specified size and with the specified 
attributes. 


Format 

\^cm_/cf=UIS$CREATE_COLOR_MAP 


vcm^size 

[,vcm—name] 

[, vcm—attributes] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the virtual color map identifier in the variable 
vcm—id or RO (VAX MACRO). The virtual color map identifier uniquely 
identifies the virtual color map and must be specified in UIS$CREATE_ 
DISPLAY. It is also used as an argument in other color routines. 

UIS$CREATE_COLOR_MAP signals all errors; no condition values are 
returned. 


Arguments 


vcm—size 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Size of the virtual color map. The vcm—size argument is the address of a 
longword that defines the number of entries in the virtual color map. 


vcm—name 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 
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Name of the virtual color map. The vcm_name argument is the address of 
a string descriptor of the name of the virtual color map. Specify the name of 
an existing shareable color map. If your application is creating the shareable 
color map, specify a valid color map name. 

The virtual color map name should not exceed 15 characters. 


vcm—attributes 


VMS Usage: 
type: 
access: 
mechanism: 


item_list_pair 
longword (unsigned) 
read only 
by descriptor 


Virtual color map attributes. The vcm_attributes argument is the address of 
data structure of longword pairs that specify virtual color attributes. 


The following figure describes the structure of this argument. 


Attribute code 
(VCMAL$C_xxxx) 

Longword value for attribute 
specified in previous longword 


2nd attribute code 


2nd attribute value 


End of list = 0 

(VCMAL$C_END_OF_LIST) 


ZK-5367-86 


All of the following virtual color map attributes are optional. 
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Attributes Function 

VCMAL$C_ATTRIBUTES General attributes 

VCMAL$M_RESIDENT Set for resident virtual color map 

VCMAL$M_SHARE Set for shareable virtual color map 

VCMAL$M_SYSTEM^’^ Set for system shareable virtual color map 

VCMAL$M_NO_BlND Set to disable automatic hardware color map binding 

WCMAL$M_SHARE must also be set. 

^SYSGBL privilege is required. 
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UIS$CREATE__COLOR_MAP-_SEG 

Allocates one or more hardware color map indices and binds them to a 
virtual color map. 

Format 

cms_/d=UIS$CREATE_COLOR_MAP_SEG vcmUd 

idevnam] 

[, place—mode] 

[, place—data] 

Returns 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism; by value 

Longword value returned as the color map segment identifier in the variable 
cms—id or RO (VAX MACRO). The color map segment identifier uniquely 
identifies the color map segment and is used as an argument in other 
routines. 

UlS$CREATE_COLOR_MAP_SEG signals all errors; no condition values 
are returned. 


Arguments 

vent—id 

VMS Usage: identifier 
type: longword (unsigned) 

access; read only 

mechanism: by reference 

Virtual color map identifier. The vcm_id argument is the address of a 
longword that uniquely identifies the virtual color map. See U1S$CREATE_ 
COLOR—MAP for more information about the vcm_id argument. 

NOTE: This routine can only be used once for each virtual color map 
identifier. 
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devnam 


VMS Usage: 
type: 
access: 
mechanism: 


device_name 
character string 
read only 
by descriptor 


Device name. The devnam argument is the address of a character string 
descriptor of the workstation device name. Specify the device name 
SYS$WORKSTATION in the devnam argument. 


place—mode 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Placement mode. The place_mode argument is the address of a longword 
that specifies the placement mode, that is, which hardware color map entries 
can be allocated. The following table lists valid placement modes. 


Symbol 

Function 

UIS$C_GENERAL 

General placement—Allocates any available entries 
in the hardware color map. 

UIS$C_COLOR_EXACT 

Exact placement—Allocates map entries starting at 
the specified entry and aligned on a natural entry 
boundary. Given the size of the virtual color map, 
UIS computes a working size that is the smallest 
power of 2 greater than or equal to the requested 
size. The natural alignment of a map is a starting 
index that is a multiple of the working size. For 
example, a six-entry color map could be placed at 
indices 0, 8, 16 and so on. 

UIS$C_COLOR_BASED 

Based placement (default)—Allocates entries such 
that writing modes using Boolean logic operations on 
pixel values can correctly display color intersections. 


place—data 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Placement data. The place—data argument is the address of a longword that 
contains the first index to be allocated. The placement—data argument is 
used with exact placement mode. 
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Description 

For hardware supporting bit plane write masks, the segment will be based 
at an index that is a power of 2 and that write operation will be performed 
using the appropriate mask. The virtual color map entry index specified in 
the place—data argument indicates the binding between the virtual color map 
and the hardware color map entries allocated by UIS$CREATE—COLOR- 
MAP—SEG. The default value is 0, that is, the first allocated map entry is 
bound to virtual color map entry 0, the second allocated map entry is bound 
to virtual color map entry 1, and so on. 

If the appropriate entries cannot be allocated, an error is signaled. In addition 
to failure due to resource depletion, a call to UIS$CREATE—COLOR—MAP— 
SEG can fail because UIS has already issued this call for the application. 
This occurs if the flag VCMAL$M—NO—BIND is not set when the virtual 
color map is created, and internal processing required a binding to hardware 
resources. For example, UISSCREATE—WINDOW allocates and binds 
hardware color map resources when creating a display viewport. 

Conversely, if VCMAL$M-NO-BIND is set, but UIS$CREATE-COLOR- 
MAP—SEG was not called, calls to some UIS routines such as UIS$SET— 
COLOR and UIS$SET-INTENSITY may fail. 

NOTE: The recommended procedure for using this routine is as follows: 

1. Specify the flag VCMAL$M—NO—BIND when creating the virtual color 
map with UIS$CREATE_COLOR-MAP. 

2. Invoke UIS$CREATE—COLOR—MAP—SEG before calling any other UIS 
routine. 

3. Initialize the color map using UIS$SET—COLORS. By definition all colors 
are black. 
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UIS$CREATE_DISPLAY 

Creates a virtual display. 

Format 

yc/_/c/=UIS$CREATE_DISPLAY Xp Yp >2, width, height 

[,vcm—id] 

Returns 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as the virtual display identifier in the variable 
vd—id or RO (VAX MACRO). The virtual display identifier uniquely identifies 
the virtual display and is used as a parameter in all output and attribute 
routines. 

UIS$CREATE—DISPLAY signals all errors; no condition values are returned. 

Arguments 

Xp yp X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the virtual display space. The Xj and yj arguments are 
the addresses of {—floating point numbers that define the lower-left corner of 
the virtual display space. The X 2 and y 2 are the addresses of f—floating point 
numbers that define the upper-right comer of the virtual display. 

These arguments define mapping and scaling factors and are not the 
boundaries of the virtual display. 

width, height 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 
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Width and height of the display viewport. The width and height arguments 
are the addresses of f_floating point numbers that define both the width and 
height of the display viewport in centimeters. 


vcm—id 


VMS Usage; 
type: 
access: 
mechanism; 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual color map identifier. The vcm_id argument is the address of a 
longword that uniquely identifies the virtual color map. See UIS$CREATE_ 
COLOR—MAP for more information about the vcm_id argument. 

If vcm—id is not specified, a two-entry virtual color map is created for the 
virtual display by default. 


Description 

To avoid distorting the resulting graphic image, the aspect ratio of the world 
coordinate range of the display window must be equal to the aspect ratio of 
the display viewport. See UIS$CREATE—WINDOW for more information 
about aspect ratios. 
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UIS$CREATE_KB 


Creates a virtual keyboard on the specified device. 


Format 

/cib_/d=UIS$CREATE>.KB devnam 


Returns 


VMS Usage; 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the virtual keyboard identifier in the variable 
kb—id or RO (VAX MACRO). The virtual keyboard identifier uniquely 
identifies the virtual keyboard. The variable kb—id is used as an argument in 
other routines. 


UIS$CREATE_KB signals all errors; no condition values are returned. 


Argument 


devnam 
VMS Usage; 
type: 
access: 
mechanism: 


device_name 
character string 
read only 
by descriptor 


Device name string. The devnam argument is the address of a character 
string descriptor of the workstation device name. Specify the logical name 
SYS$WORKSTATION as the device name string. 


Description 

U1S$CREATE_KB generates a value for the kb_id argument which is 
referenced in subsequent routines that use kb_id as a parameter. 
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Example 


VD_ID=UIS$CREATE_DISPLAY(-5.0,-5.0.50.0.45.0,15.0,15.0) 
KB_ID=UIS$CREATE_KB(’SYS$W0RKSTATI0N’) O 

WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$W0RKSTATI0N’,’VIEWPORT TITLE’, 

2 10.0,10.0,25.0,25.0) 

CALL UIS$ENABLE_VIEWPORT_KB(KB_ID,WD_ID) Q 

CALL UIS$DISABLE_VIEWPORT_KB(WD_ID) © 

The preceding example creates a virtual keyboard O and binds the virtual 
keyboard to a display window In order to use the virtual keyboard and 
its characteristics with the desired viewport, you must assign the physical 
keyboard to the desired virtual keyboard and viewport. Press the F5 or 
I cycle I key until the KB icon in the appropriate viewport is highlighted. 

The call to UIS$DISABLE_VIEWPORT_KB © explicitly disables the binding 
between the virtual keyboard and the display window. Also, the ability to 
assign the physical keyboard to the appropriate virtual keyboard, that is, to 
cycle from viewport to viewport, is disabled. 

If UIS$ENABLE_KB were called after UIS$ENABLE_VIEWPORT_KB, the 
KB icon would have been highlighted as soon as the program executed. 
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Illustration 

WD_ID4 



ZK-5452-86 
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UIS$CREATE_TB 

Creates a tablet digitizer identifier that allows you to connect your process to 
the tablet. 


Format 

f/?_/cf=UIS$CREATE_TB devnam 


Returns 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Longword value returned as the tablet identifier in the variable tb—id or RO 
(VAX MACRO). The tablet identifier uniquely identifies the tablet device and 
can be used in other routines where appropriate. 

UIS$CREATE_TB signals all errors; no condition values are returned. 


Argument 


devnam 

VMS Usage: 
type: 
access: 
mechanism: 


device—name 
character string 
read only 
by descriptor 


Device name. The devnam argument is the address of a character string 
descriptor of the workstation device name. Specify SYS$WORKSTATION as 
the default device name character string. 


Description 

UIS$CREATE_TB creates a tablet digitizer identifier. When you want 
to connect to the tablet, you must specify this identifier in a call to 
U1S$ENABLE_TB. 
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UIS$CREATE-TERMINAL 

Creates a terminal emulation window of the specified type. 

Format 

UIS$CREATE_TERMINAL termtype [,title] [,attributes] 

idevnam] [,devlen] 

Returns 

UIS$CREATE—TERMINAL signals all errors; no condition values are 
returned. 


Arguments 

termtype 

VMS Usage: char—string 
type: character string 

access: read oniy 

mechanism: by descriptor 

Terminal type. The termtype argument is the address of a character string 
descriptor of the terminal type. Specify either WT for a VT220 emulation 
window or TK for a TEK4010/4014 emulation window. 

title 

VMS Usage: char—string 
type: character string 

access: read oniy 

mechanism: by descriptor 

Window title. The title argument is the address of a descriptor of a character 
string that is the title of the terminal emulation window. 

attributes 

VMS Usage: item—iist—pair 
type: iongword 

access: read oniy 

mechanism: by reference 

Window attributes list. The attributes argument is the address of a data 
structure that contains two or more longwords. The list consists of one or 
more Iongword pairs, or doublets. The first Iongword contains an attribute 
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code, while the second longword holds an attribute value (which can be real 
or integer). The constant WDPL$C__END_OF_LIST terminates the list. 


The window attributes list has the same format as defined in the 
UIS$CREATE—WINDOW service. If your application program is written 
in FORTRAN, use the RECORD data type to construct the attribute list. 
Refer to UIS$CREATE—WINDOW for a description of the attribute list. 


devnam 


VMS Usage: 
type: 
access: 
mechanism: 


device—name 
character string 
write only 
by descriptor 


New terminal emulation device name. The devnam argument is the address 
of a character string descriptor of a location that receives the new terminal 
emulation device name string. 


devlen 


VMS Usage: 
type: 
access: 
mechanism: 


word—unsigned 
word (unsigned) 
write only 
by reference 


Length of the terminal emulation device name string. The devlen argument 
is the address of a word that receives the length of the terminal device name 
character string. 


Description 

UIS$CREATE—TERMINAL creates a pseudodevice in the VMS database 
and returns the device name string for the device. The window may not 
appear on the screen until a channel is assigned to the device using the 
SYS$ASSIGN system service and the first write to the device is performed. 

The pseudodevice is created without any initial owner. Once a channel is 
assigned to the device, it is owned by that process, which is usually the same 
process that issued the UIS$CREATE—TERMINAL call. After all channels 
have been deassigned, the pseudodevice will be removed automatically from 
the system. If a permanent pseudodevice is required, then the application 
should specify a process that maintains a permanent channel to the device. 
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UIS$CREATE_TRANSFORMATION 

Creates a two-dimensional world coordinate transformation into an existing 
virtual display's coordinate space. It provides for two-dimensional translation 
and scaling, but not rotation. 

Format 

fr_/d=UIS$CREATE-.TRANSFORMATION vd-id, Xp 

X2,y2[,vdxp 
vdypVdX2, vdyj 

Returns 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as the transformation identifier in the variable 
tr^id or RO (VAX MACRO). The transformation identifier uniquely identifies 
a transformation coordinate space. See the "DESCRIPTION" section below 
for more information about fr_zd. 

UIS$CREATE—TRANSFORMATION signals all errors; no condition values 
are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

Xi, Yi, X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 
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World coordinates of the new coordinate space. The Xj and yj arguments 
and the X 2 and 72 arguments are the addresses of f—floating point numbers 
that define the lower-left comer and upper-right comer of the new 
transformation coordinate space, respectively. 

vdxi, vdyi, vdX2, vdy2 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the original virtual display space. The vdxj and vdy^ 
arguments are the addresses of f—floating point numbers that define the 
lower-left comer of the corresponding virtual display space. The vdx 2 and 
vdy 2 arguments are the addresses of f—floating point numbers that define 
the upper-right comer of the corresponding virtual display space. If these 
optional arguments are not specified, the world coordinates specified in 
UIS$CREATE-DISPLAY are used. 


Description 

Once the transformation is created, it can be used in any routine that accepts 
a vd—id argument except UIS$DELETE—DISPLAY by substituting the tr—id 
argument instead. When the tr—id value is used, it indicates the same virtual 
display but that the coordinates are mapped relative to the transformation 
coordinate space, and not the original virtual display coordinate space. Each 
routine automatically performs the transformation. 
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(50,30) 


Original 

World Coordinate 
Space 


New World Coordinate Space 
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UIS$CREATE_WINDOW 

Creates a display window and an associated display viewport. See 
UIS$GET_WINDOW_ATTRIBUTES for information about window attributes. 


Format 

wdL/Gf=UIS$CREATE^WINDOW 


vd—id, devnam [,title] [,Xp 
Yp ^2^ y2][,width, height] 
[,attributes] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the display window identifier in the variable 
wd—id or RO (VAX MACRO). The display window identifier uniquely 
identifies the display window and is used as an argument in other routines. 

UIS$CREATE—WINDOW signals all errors; no condition values are returned. 


Arguments 


vd-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
value that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY 
for more information about the vd_id argument. 


devnam 


VMS Usage: 
type: 
access: 
mechanism: 


device—name 
character string 
read only 
by descriptor 
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Device name. The devnam argument is the address of a character string 
descriptor of the display device on which the display viewport is created. 
Specify the logical name SYS$WORKSTATION as the name of the device. 


title 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Banner title. The title argument is the address of a descriptor of the character 
string to be inserted into the banner of the display viewport. If the argument 
title is not specified, the display banner is created without a title. 


Xu yi X2, Yi 

VMS Usage: 
type: 
access: 
mechanism: 


floating_point 
f_floating 
read only 
by reference 


World coordinates of the display window. The Xj, ji and Xi, ji arguments 
are addresses of f—floating point numbers that define the lower-left comer 
and upper-right comer of the display window rectangle. The display 
window rectangle defines the visible portion of the virtual display. The 
world coordinate space of the display window rectangle is mapped to the 
display screen as the display viewport. 

If these coordinates are not specified, the entire world coordinate space 
specified in the UIS$CREATE—DISPLAY routine is used. 


width, height 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Initial dimensions of the display viewport. The width and height arguments 
are addresses of f—floating point numbers that define the width and height of 
the display viewport in centimeters. If the width and height arguments of 
the display viewport specified in UIS$CREATE—WINDOW are different from 
the width and height arguments specified in the UIS$CREATE—DISPLAY 
routine, the default values of UIS$CREATE—DISPLAY are overridden and 
scaling occurs. 

If the world coordinates of the display window are specified and the width 
and height arguments are not specified, the default dimensions of the 
display viewport are calculated from the ratios of the world coordinate 
values and the width and height specified in UIS$CREATE—DISPLAY. See 
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the Description section for more information about calculating the default 
display viewport dimensions. 

Display viewports that are too large to fit on the screen are automatically 
proportionally scaled in size. 


attributes 


VMS Usage: 
type: 
access: 
mechanism: 


itemJist—pair 

longword integer (signed) or f_fioating 
read oniy 
by reference 


Display viewport attribute list. The attributes argument is the address of a 
data structure that contains longword pairs, or doublets. The first longword 
stores an attribute ID code and the second longword holds the attribute 
value (which can be real or integer). The constant WDPL$C_END_OF_LIST 
terminates this list. FORTRAN application programs should create a record 
using the RECORD statement to construct this list. It has the following 
format. 


Attribute ID code 
(WDPL$C_xxx) 

Longword value for attribute 
identified in previous longword 


2nd attribute ID code 


2nd attribute value 


End of list = 0 

(WDPL$C_END_OF_LIST) 


ZK-4581-85 

Window attributes are optional and control window placement and attributes. 
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Attribute 

WDPL$C_ABS_POS_X 


WDPL$C_ABS_POS_Y 


WDPL$C_PLACEMENT 


Description 

Exact X placement on the screen. 

This attribute defines the x origin of the viewport relative to 
the lower-left comer of the screen. The value is expressed 
as an f_floating point number of centimeters. Note that the 
actual point WDPL$C_ABS_POS_X defines is the lower left 
comer of the display viewport without the border. Along with 
WDPL$C_ABS_POS_Y, this provides the ability to place 
exactly a new viewport at a specific position anywhere on the 
workstation screen. 

Exact y placement on the screen. 

This attribute defines the y origin of the viewport relative to 
the lower-left comer of the screen. The value is expressed 
as an f_iloating point number of centimeters. Note that the 
actual point WDPL$C__ABS_POS_Y defines is the lower-left 
comer of the display viewport without the border. Along with 
WDPL$C_ABS_JOS_X, this attribute provides the ability to 
place exactly a new viewport at a specific position anywhere on 
the workstation screen. 

Display viewport placement flags. 

The attribute list is a longword bit vector providing viewport 
placement information. The preference masks (top, bottom, 
left, and right) may be combined by setting more than one bit 
in the bit vector. If the screen becomes crowded, the system 
may override the preference masks. 

• WDPL$M_TOP — The display viewport is placed near 
the top of the physical display 

• WDPL$M—BOTTOM — The display viewport is placed 
near the bottom of the physical display 

• WDPL$M—LEFT — The display viewport is placed near 
the left side of the physical display 

• WDPL$M—RIGHT — The display viewport is placed near 
the right side of the physical display 

• WDPL$M—CENTER — The display viewport is centered 
over the position specified by WDPL$C—ABS—POS—X and 
WDPL$C-ABS-POS-Y. 
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Attribute 


WDPL$C_ATTRIBUTES 


Description 

• WDPL$M—INVISIBLE — The display viewport is created 
invisibly, that is, off the screen and, hence, cannot be seen. 

• Other bits — The remaining bits are reserved to DIGITAL 
and must be set to zero. 

Display viewport attributes. 

This data structure argument causes the display viewport to 

be created with one or more of the following attributes. These 

attributes are specified as bits in a longword mask. 

• WDPL$M—ALIGNED—The left inner edge of the display 
viewport is to be aligned on byte boundaries. Applications, 
such as the VT220 terminal emulator, can use WDPL$M_ 
ALIGNED to take advantage of text drawing performance 
optimizations when 8-bit characters are written on byte 
boundaries. 

• WDPL$M_NOBANNER—The display viewport is created 
without a banner. If a banner title was specified, it is 
ignored. 

• WDPL$M_NOBORDER—The display viewport is 
created without a border. When you specify WDPL$M_ 
NOBORDER, the attribute WDPL$M-NOBANNER is 
implied. A viewport created without a border cannot be 
moved with the user interface. 

• WDPL$M—NOKB—ICON—The display viewport banner 
is created without a KB icon. Specify this attribute, if you 
are sure the application will never require a KB icon or 

if you wish to add more space in the banner for the title. 
Otherwise, UIS saves an extra quarter of an inch in the 
banner for the KB icon. 

• WDPL$M—NOMENU—ICON—The display viewport 
banner is created without a menu icon. Therefore, the 
Window Options Menu cannot be activated. 

• Other bits—The remaining bits are reserved to DIGITAL 
and must be zero. 
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Attribute 

Description 

WDPL$C_END_OF_LIST 

Terminates attributes list. 

This must be the last longword in the attribute list. It does not 
require an associated longword value. 



Description 

UIS$CREATE—WINDOW defines a portion of the virtual display that lies 
within the display window and that is mapped to the display screen as the 
display viewport. 

Default Dimensions of the Display Viewport 

Whenever the world coordinates of the display window are defined, but the 
dimensions of the display viewport are not specified, the system calculates 
the default dimensions of the display viewport using the appropriate 
arguments from each routine as shown in the following figure. The size 
of the display viewport is based on the width and height arguments in 
UIS$CRE ATE-DISPLAY in the following manner: 

UIS$CREATE_DISPLAY UIS$CREATE_WINDOW 

width new_width 


X2 - xi 


X2 - Xi 


height new_height 


y2 - yi y2 - yi 


ZK-5462-86 


The variables new—width and new—height represent unknown quantities, 
the default dimensions of the display viewport. All other variables are the 
parameters used in the respective routine calls. 

For example, the viewport that is created in the following example is 4 
centimeters wide and 2 centimeters high. 

vd_id=UIS$CREATE_DISPLAY(0.0,0.0,1.0,1.0,8.0,4.0) 
wd_id=UIS$CREATE_WINDOW(vd_id,’SYS$W0RKSTATI0N’,’TEST WINDOW’. 

0.0,0.0,0.5,0.5) 

Otherwise, these values can be overridden with the optional width and 
height arguments in UIS$CREATE—WINDOW. 
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Display Viewport Creation 

Display viewports are always created completely on or off the display screen. 

Distortion of Graphic Objects 

To avoid distortion of graphic objects, the aspect ratios of the display window 
and the display viewport must be equal. 


(x1,y1) 


(xO.yO) 


(xl,yO) 


Height 


Width 

2K-4582-85 


In the preceding illustration, the aspect ratio of the display window on the 
left does not appear to be equal to the aspect ratio of the viewport on the 
right. 

You can compare aspect ratios using the following equation. 


y1 - yO I viewport height 

I x1 - xO I viewport width 

ZK-4579-85 

The aspect ratio of the display viewport is the absolute value of the height 
divided by the absolute value of the width. 
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Example 


PROGRAM EXAMPLE.A 


STRUCTURE/STRUCT/ O 
INTEGER+4 CODE.l 
REAL*4 ATTRIB.l 
INTEGER*4 C0DE_2 
REAL*4 ATTRIB_2 
INTEGER*4 C0DE_3 
INTEGER+4 ATTRIB_3 
INTEGER*4 END 
END STRUCTURE 

RECORD/STRUCT/WINDOW © 

WINDOW.C0DE_1=WDPL$C_ABS_P0S_X 

WINDOW.ATTRIB_1=10.5 

WINDOW.CODE_2=WDPL$C_ABS_POS_Y 

WINDOW.ATTRIB_2=13.25 

WINDOW.C0DE_3=WDPL$C_ATTRIBUTES 

WINDOW.ATTRIB_3=WDPL$M_N0KB_IC0N .OR. WDPL$M_NOMENU_ICON 
WINDOW.END=WDPL$C_END_OF_LIST 


VD_ID=UIS$CREATE_DISPLAY(-10.0.-10.0.35.5.35.5,16.0.16.0) O 

WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$WORKSTATION’,’LOOK’,2.0,2.0.28.0,28.0 
2 20.0,20.0,WINDOW) O 


The preceding example describes how to construct the data structure 
argument used in UIS$CREATE—WINDOW to enable viewport placement 
and characteristics O 0. In addition, the example illustrates the minimum 
number of calls used to create a display window © O. 
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Screen Output 



ZK-5278-86 





18-46 UlS Routine Descriptions 
UIS$DELETE_COLOR-MAP 


UIS$DELETE-COLOR_MAP 


Deletes a virtual color map. 


Format 

UIS$DELETE_COLOR^MAP vcmUd 


Returns 

UIS$DELETE—COLOR—MAP signals all errors; no condition values are 
returned. 


Argument 


vcm—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual color map identifier. The vcm—id argument is the address of a 
longword that uniquely identifies the virtual color map. See UIS$CREATE— 
COLOR—MAP for more information about the vcm_id argument. 


Description 

An attempt to delete an active virtual color map, that is, a virtual color map 
associated with one or more virtual displays, signals an error. 

All virtual displays that reference the virtual color map should be deleted 
first using UIS$DELETE-DISPLAY. 
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UIS$DELETE_COLOR_MAP_SEG 


Deletes the specified color map segment. 


Format 

UIS$DELETE_COLOR_MAP_SEG cms-id 


Returns 

U1S$DELETE—COLOR _MAP_SEG signals all errors; no condition values are 
returned. 


Argument 


cms—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Color map segment identifier. The cms_id argument is the address of a 
Iongword that uniquely identifies the color map segment to be deleted. See 
U1S$CREATE—COLOR-MAP—SEG for more information about the cms—id 
argument. 


Description 

Color map segment deletion has no effect on the colors being mapped by 
the hardware color map. The deletion of color map segments marks the 
corresponding entries as available for allocation. 

An attempt to delete an active color map segment, that is, a color map 
segment referenced by a virtual color map, signals an error. 

The virtual color map should be deleted first using UIS$DELETE—COLOR- 
MAP. 
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UIS$DELETE_DISPLAY 


Deletes the virtual display, all associated windows, and viewports. 


Format 

UIS$DELETE_DISPLAY vd-id 


Returns 

UIS$DELETE—DISPLAY signals all errors; no condition values are returned. 


Argument 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


Description 

You cannot substitute the tr—id argument for the virtual display identifier in 
this routine. 
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UIS$DELETE^KB 

Deletes a virtual keyboard. If the specified virtual keyboard is bound to a 
window or to the physical keyboard, those bindings are terminated. 


Format 

UIS$DELETE_KB kbUd 


Returns 

UIS$DELETE_KB signals all errors; no condition values are returned. 


Argument 


kbUd 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual keyboard identifier. The kb—id argument is the address of a 
Iongword that uniquely identifies a virtual keyboard. See UIS$CREATE_ 
KB for more information about the kb—id argument. 


Description 

UIS$DELETE—KB may be used to delete a virtual keyboard at any time 
within a program. 
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UIS$DELETE_OBJECT 


Deletes the specified object from the virtual display. 


Format 

UIS$DELETE_OBJECT ( \ 

I seg-id ) 


Returns 

U1S$DELETE—OBJECT signals all errors; no condition values are returned. 


Arguments 


obj—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Object identifier. The obj_id argument is the address of a Iongword that 
uniquely identifies the object to be deleted. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Segment identifier. The seg-id argument is the address of a Iongword that 
uniquely identifies the segment. See UIS$BEG1N_SEGMENT for more 
information about the seg_id argument. 


Description 

The screen is updated immediately to reflect the new state of the virtual 
display. If it is impossible to modify only those portions which have 
changed, then the entire display may be replotted. Occluded objects are 
always refreshed. 
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UIS$DELETE_PRIVATE 


Deletes the private data associated with the object. 


Format 

UIS$DELETE_PRIVATE | \ 

I seg-id ) 


Returns 

UIS$DELETE—PRIVATE signals all errors; no condition values are returned. 


Arguments 


obi—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Object identifier. The obj—id argument is the address of a longword that 
uniquely identifies an object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg—id argument is the address of a longword that 
uniquely identifies the segment. See UIS$BEGIN—SEGMENT for more 
information about the seg—id argument. 


Description 

If more than one private data item exists, all private data items are deleted. 
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UIS$DELETE-_TB 

Deletes the tablet digitizer identifier and disconnects the application from the 
tablet. 


Format 

UIS$DELETE«_TB tbUd 


Returns 

UIS$DELETE_TB signals all errors; no condition values are returned. 


Argument 


tb—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Tablet identifier. The tb_id argument is the address of a Iongword that 
uniquely identifies the tablet device. See U1S$CREATE_TB for more 
information about the tb_id argument. 


Description 

U1S$DELETE_TB deletes a tablet digitizing identifier. When your process 
has completed digitizing, you should call this routine to delete the identifier. 
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UIS$DELETE.TRANSFORMATION 

Deletes a world coordinate transformation of a virtual display. The 
corresponding virtual display is not affected. 


Format 

UIS$DELETE--TRANSFORMATION trUd 


Returns 

UIS$DELETE—TRANSFORMATION signals all errors; no condition values 
are returned. 


Argument 


tr—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Transformation identifier. The tr—id argument is the address of a longword 
that uniquely identifies the transformation to be deleted. See UIS$CREATE_ 
TRANSFORMATION for more information about the tr_id argument. 
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UIS$DELETE_WINDOW 


Deletes an existing display window and viewport. 


Format 

UIS$DELETE_WINDOW wd-id 


Returns 

UIS$DELETE_WINDOW signals all errors; no condition values are returned. 


Argument 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window to be deleted. See 
UIS$CREATE—WINDOW for more information about the argument wd_id. 


Description 

UIS$DELETE—WINDOW deletes the display window specified by the 
wd_id argument. The associated viewport is removed from the screen. The 
virtual display associated with this display window is neither modified nor 
destroyed during the execution of this service. 
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UIS$DISABLE-DISPLAY_LIST 


Disables specified display list functions. 


Format 

UIS$DISABLE JISPLAY_LIST vd-id [,display-flags] 


Returns 

UIS$DISABLE_DISPLAY_LIST signals all errors; no condition values are 
returned. 


Arguments 


vcL-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display whose display list should be 
disabled. See UIS$CREATE—DISPLAY for more information about the 
vd—id argument. 


display—flags 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 


Display list flags. The display—flags argument is address of a longword 
mask that controls display screen and display list updates. 

The following table describes the flags and masks. 
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Flag 

Description 

UIS$M_DL_ENHANCE_LIST 

Controls making additions to the display list. 
When disabled, no new dislay list entries 
are made. This flag is set by default when a 
virtual display is created. 

UIS$M_DL -MODIFY-LIST 

Controls display list modifications. When 
disabled, no display list editing is allowed. 
This flag is set by default when a virtual 
display is created. 

UIS$M_DL -UPDATE-WINDOW 

Controls drawing. When disabled, no 
drawing or update occurs. This flag is set 
by default when a virtual display is created. 

The following table lists UIS routines that check the flags. 

Flag 

UIS Routine 

UIS$M_DL -MODIFY-LIST^ 

UIS$COPY-OBJECT 

UIS$DELETE-OBJECT 

UIS$ERASE 

UIS$INSERT-OBJECT 

UIS$MOVE-AREA 

UIS$TRANSFORM-OBJECT 

UIS$M -DL -ENHANCE -LIST^ 

UIS$CIRCLE 

UIS$ELLIPSE 

UIS$EXECUTE 

UIS$EXECUTE-DISPLAY 

UIS$IMAGE 

UIS$LINE 

UIS$LINE-ARRAY 

UIS$PLOT 

UIS$PLOT-ARRAY 

UIS$TEXT 

Ull routines listed under UIS$M_DL_ENHANCE_LIST and UIS$M_DL-MODIFY-LIST 
will also check the state of UIS$M—DL—UPDATE—WINDOW before doing any screen updates. 


If a bit is set in the mask, the corresponding function is disabled. If the bit is 
0, the corresponding function is not changed. See UIS$EN ABLE-DISPLAY- 
LIST for information on how to enable functions. 

If display—flags is not specified, UIS$M^DL—ENHANCE—LIST is disabled. 
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Description 

UIS$DISABLE_DISLAY_LIST is useful in applications such as animation. In 
such a case, display list additions are neither necessary nor desired because 
of the additional overhead. 


Example 

At some point in your application you may wish to perform several 
modifications to the display list without seeing the screen change. 


display_flags= UIS$M_DL_UPDATE_WINDOW 


CALL UIS$DISABLE_DISPLAY_LIST(VD_ID. DISPLAY.FLAGS) 


Insert your modifications here 


CALL UIS$ENABLE_DISPLAY_LIST(VD_ID. DISPLAY.FLAGS) 

CALL UIS$EXECUTE(VD_ID) ! Erases and redraws the virtual display 
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UIS$DISABLE_KB 

Disconnects the physical keyboard from the specified virtual keyboard. See 
the example in UIS$CREATE_KB for more information. 


Format 

UIS$DISABLE_KB kb-id 


Returns 

UIS$DISABLE_KB signals all errors; no condition values are returned. 


Argument 


kb—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual keyboard identifier. The kb_id argument is the address of a 
longword that uniquely identifies the virtual keyboard to be disabled. See 
UIS$CREATE_KB for more information about the kb_id argument. 
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UIS$DISABLE_TB 


UIS$DISABLE.TB 


Disconnects the digitizing tablet. 


Format 

UIS$DISABLE-TB tb-id 


Returns 

UIS$DISABLE_TB signals all errors; no condition values are returned. 


Argument 


tb-id 


VMS Usage; 
type: 
access; 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Tablet identifier. The tb_id argument is the address of longword that 
uniquely identifies the tablet device. See U1S$CREATE_TB for more 
information about the tb_id argument. 


Description 

UIS$DISABLE_TB disconnects your process from the tablet. This routine 
reenables the system pointer and frees the tablet for use by another process. 
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UIS$DISABLE-VIEWPORT-KB 


UIS$DISABLE_VIEWPORT_KB 

Prevents the user from assigning the physical keyboard to a viewport. See 
the example in UIS$CREATE_KB for more information. 


Format 

UIS$DISABLE_VIEWPORT_KB wd-id 


Returns 

UIS$DISABLE_VIEWPORT_KB signals all errors; no condition values are 
returned. 


Argument 


wd—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies a display window. The associated viewport 
of the display window is disabled. See UIS$CREATE—WINDOW for more 
information about the wd—id argument. 


Description 

UIS$DISABLE—VIEWPORT—KB removes the display window from the 
assignment list. You can no longer use the I cycle I key to make the viewport 
active. Use UIS$ENABLE-VIEWPORT_KB or UIS$ENABLE-KB to place 
the display window on the assignment list. 
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UIS$ELLIPSE 

Draws an arc along the circumference of an ellipse. 

Format 

UIS$ELLIPSE vd—id, atb, centers, center—y, xradius, 
yradius [,start—deg,end—deg] 

Returns 

U1S$ELLIPSE signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd—id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about vd_id argument. 

atb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a Iongword 
integer that identifies the attribute block that will modify the ellipse. If you 
specify 0 in the atb argument, the default settings of attribute block 0 are 
used. 

center—X, center—y 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 
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UIS$ELLIPSE 


Center position x and y world coordinates. The center_x and center_y 
arguments are the addresses of f_floating point numbers that define a point 
in the virtual display that is the center of the ellipse or arc. 

xradius 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Radius of the ellipse specified as an x world coordinate width. The xradius 
argument is the address of an f—floating point number that defines the 
distance from the center of the ellipse to the circumference of the ellipse or 
arc. 

yradius 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Radius of the ellipse specified as a y world coordinate width. The yradius 
argument is the address of an f—floating point number that defines the 
distance from the center of the ellipse to the circumference of the ellipse or 
arc. 

start—deg, end—deg 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Degree at which the arc starts and ends. The start—deg and end—deg 
arguments are the addresses of f—floating numbers that define the starting 
point and ending point in degrees on the circumference of the ellipse where 
the arc or ellipse will be drawn. Degrees are measured clockwise from the 
top of the ellipse. If these arguments are not specified, 0.0 and 360.0 degrees 
are assumed. If both arguments are not specified, a complete ellipse is 
drawn. 


Description 

UIS$ELLIPSE uses center position coordinates and x and y radii to construct 
an ellipse. Along the circumference of this ellipse, UIS$ELLIPSE draws an 
arc for a specified range of degrees. 
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The arc is closed by drawing one or more lines between the endpoints. The 
type of arc associated with the attribute block specifies the way in which the 
arc is closed. See the UIS$SET_ARC_TYPE routine. 

The points are drawn with the current line pattern and width, and filled with 
the current fill pattern, if enabled. 

UIS$ELLIPSE does not support the following combination of attributes: 

• Line width not equal to 1 and line style not equal to FFFFFFFFi^ 

• Line width not equal to 1 and complement writing mode 

Ellipses are distorted by differences between the aspect ratios of the virtual 
display and display window. 
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UISSELLIPSE 


Screen Output 
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UIS$ENABLE_DISPLAY-LIST 


UIS$ENABLE_>DISPLAY-.LIST 


Reenables automatic additions to the display list. 


Format 

UIS$ENABLE_DISPLAY^LIST vdUd [, display-flags] 


Returns 

UIS$ENABLE_DISPLAY_LIST signals all errors; no condition values are 
returned. 


Arguments 


vtLJd 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display whose display list is to be 
enabled. See UIS$CREATE—DISPLAY for more information about the 
vd—id argument. 


display—flags 

VMS Usage: mask—longword 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 


Display list flags. The display—flags argument is the address of a Iongword 
mask that controls display screen and display list updates. 

The following table describes the flags and masks. 
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UIS$ENABLE-DISPLAY_LIST 


Flag 

Description 

U1S$M_DL _ENHANCE_LIST 

Controls making additions to the display list. 
When disabled, no new dislay list entries 
are made. This flag is set by default when a 
virtual display is created. 

UIS$M _DL _MODIFY_LIST 

Controls display list modifications. When 
disabled, no display list editing is allowed. 
This flag is set by default when a virtual 
display is created. 

UIS$M_DL -UPDATE-WINDOW 

Controls drawing. When disabled, no 
drawing or update occurs. This flag is set 
by default when a virtual display is created. 

The following table lists UIS routines that check the flags. 

Flag 

UIS Routine 

UIS$M-DL -MODIFY-LIST^ 

UIS$COPY-OBJECT 

UIS$DELETE-OBJECT 

UIS$ERASE 

UIS$INSERT-OBJECT 

UIS$MOVE-AREA 

UIS$TRANSFORM_OBJECT 

UIS$M -DL -ENHANCE -LIST^ 

UIS$CIRCLE 

UIS$ELLIPSE 

UIS$EXECUTE 

UIS$EXECUTE-DISPLAY 

UIS$IMAGE 

UIS$LINE 

UIS$LINE-ARRAY 

UISSPLOT 

UIS$PLOT_ARRAY 

UIS$TEXT 

1a 11 routines listed under UIS$M_DL_ENHANCE_LIST and UIS$M_DL_MODlFY_LIST 

will also check the state of U1S$M—DL. 

-UPDATE—WINDOW before doing any screen updates. 


If a bit is set in the mask, the corresponding function is disabled. If the bit is 
0, the corresponding function is not changed. 

If display—flags is not specified, UIS$M_DL—ENHANCE—LIST is disabled. 
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Example 

At some point in your application you may wish to perform several 
modifications to the display list without seeing the screen change. 


display_flags= UIS$M_DL_UPDATE_WINDOW 


CALL UIS$DISABLE_DISPLAY_LIST(VD_ID. DISPLAY.FLAGS) 


Insert your modifications here 


CALL UIS$ENABLE_DISPLAY_LIST(VD_ID. DISPLAY.FLAGS) 

CALL UIS$EXECUTE(VD_ID) ! Erases and redraws the virtual display 
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UIS$ENABLE_KB 

Connects the physical keyboard to the specified virtual keyboard. See the 
example in UIS$CREATE_KB for more information. 


Format 

UIS$ENABLE^KB kb-id [,wd-icl] 


Returns 

UIS$ENABLE_KB signals all errors; no condition values are returned. 


Arguments 


kb—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual keyboard identifier. The kb-id argument is the address of a 
Iongword that uniquely identifies the virtual keyboard to be connected to 
a physical keyboard. See UIS$CREATE_KB for more information about the 
kb-id argument. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd-id argument is the address of a 
Iongword that uniquely identifies the display window whose KB icon should 
be highlighted. See UIS$CREATE—WINDOW for more information about 
the wd_id argument. 
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UiS$ENABLE-KB 


Description 

Because it is desirable to leave control of the keyboard to the user, it is 

recommended that you use the UIS$ENABLE_KB as little as possible. 

However, there are times when you may want to use it. 

• When you are starting up a new application. In this case, the user may 
want the workstation keyboard to be implicitly connected to a new 
application. 

• When the physical keyboard is already connected to the application (as 
determined by the UIS$TEST_KB routine). In this case, the application 
may wish to facilitate movement of the keyboard between its windows. 

Note that these are not restrictions imposed by the workstation software. 
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UIS$ENABLE-TB 


Assigns the tablet to the calling process. 


Format 

UIS$ENABLE_TB tbUd 


Returns 

UIS$ENABLE_TB signals all errors; no condition values are returned. 


Argument 


tb—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Tablet identifier. The tb_id argument is the address of a Iongword 
that uniquely identifies a tablet device. See UIS$CREATE_TB for more 
information about the tb-id argument. 


Description 

Only one application may own the tablet at one time. When a process 
connects to the tablet, the system hardware cursor is turned off and the 
connected process receives all the input from the tablet device. The process 
owns the tablet until it calls UIS$DISABLE_TB to disconnect itself from the 
tablet. 

The process must use a software cursor to track the pointer in a display 
window. 
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UIS$ENABLE_VIEWPORT_KB 

Allows the user to assign a virtual keyboard to the physical keyboard and 
signals binding through the KB icon in the viewport banner. See the example 
in UIS$CREATE_KB for more information. 


Format 

UIS$ENABLE_VIEWPORT_KB kb-id, wd-id 


Returns 

UIS$ENABLE—VIEWPORT_KB signals all errors; no condition values are 
returned. 


Arguments 


kb-id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual keyboard identifier. The kb_id argument is the address of a 
longword that uniquely identifies the virtual keyboard. See UIS$CREATE_ 
KB for more information about the kb—id argument. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE— 
WINDOW for more information about the wd—id argument. 


Description 

UIS$ENABLE—VIEWPORT—KB makes the display window as a KB handle. 
The viewport contains a nonhighlighted KB icon. 
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UIS$END_SEGMENT 


Ends a current segment in a virtual display. 


Format 

UIS$END_SEGMENT vd-id 


Returns 

UIS$END_SEGMENT signals all errors; no condition values are returned. 


Argument 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


Description 

Context is returned to the parent segment. All values of attribute blocks 0 to 
255 are restored to the current values of the parent's attribute blocks. 
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m$$ERASE 

UIS$ERASE 

Erases the specified rectangle in the virtual display and removes all entities 
that lie completely within the rectangle from the display list. 

Format 

UIS$ERASE vd—id[,XpypX2,y2] 

Returns 

UIS$ERASE signals all errors; no condition values are returned. 


Arguments 

vdJid 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display containing the specified rectangle. 
See UIS$CREATE—DISPLAY for more information about the vd_id 
argument. 

xp yp X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinate pairs. The and y^ arguments are the addresses of 
f—floating point numbers that define the lower-left comer of the rectangle in 
the virtual display. The X 2 and y 2 arguments are the addresses of 
f—floating point numbers that define the upper-right comer of the rectangle 
in the virtual display. If no rectangle is specified, the entire virtual display is 
erased. 
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Description 

UIS$ERASE removes all graphics entities that lie completely within the 
rectangle from the display list as if they had never been written. Objects that 
do not lie completely within the specified rectangle are not erased. Empty 
segments are not deleted. 

Areas within the display window affected by this routine are filled with color 
specified by entry 0 in the color map of the virtual display. 
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UIS$EXECUTE 

Executes a binary encoding stream in a specified virtual display. 

Format 

UIS$EXECUTE vd-id [,buflen] [,bufaddr] 

Returns 

UIS$EXECUTE signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

buflen 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read oniy 

mechanism: by reference 

Length of the binary encoding stream. The buflen argument is the address 
of longword that contains the length of the binary encoding stream. 

bufaddr 

VMS Usage: vector_longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: reference 

Binary encoding stream. The bufaddr argument is the address of an array of 
longwords that comprise the binary encoding stream. 
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Description 

If the buffer is omitted, all display windows are erased and refreshed. 
Note the effects of the display list flags. 
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UIS$EXECUTE-_DISPLAY 

Creates a virtual display from a display list. 

Format 

YOf_/c:/=UIS$EXECUTE_DISPLAY buflen, bufaddr 

Returns 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Longword value returned as the virtual display identifier in the variable 
vd-id or RO (VAX MACRO). 

UIS$EXECUTE—DISPLAY signals all errors; no condition values are returned. 

Arguments 

buflen 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Buffer length. The buflen argument is the address of a longword that defines 
the length of the buffer. 

bufaddr 

VMS Usage: vector—byte_signed 
type: byte integer (signed) 

access: read only 

mechanism: by reference 

Buffer address. The bufaddr argument is the address of an array of integer 
bytes that contains the binary encoded stream. 

The binary encoded stream is executed in the virtual display. 
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UIS$EXPAND^ICON 

Replaces an icon with its associated viewport. 


Format 

UIS$EXPAND_ICON wd-id [,icon-wd-id] [,attributes] 


Returns 

UIS$EXPAND_ICON signals all errors; no condition values are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Display window identifier. The wd-id argument is the address of a 
Iongword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

icon—wd—id 

VMS Usage: identifier 

type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Icon window identifier. The icon_wd_id argument is the address of a 
Iongword that uniquely identifies the icon window. 

If the icon-.wd_id argument is specified, it must match the value of the 
icon_wd_id argument specified in UIS$SHRINK_TO_ICON. 

attributes 

VMS Usage: item.list—pair 

type: iongword integer (signed) or f—floating 

access: read oniy 

mechanism: by reference 

Viewport attributes list. The attributes argument is the address of data 
structure such as an array or record. The attributes can be used to specify 
exact placement of the display viewport. 
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Attribute ID code 
(WDPL$C_xxx) 

Longword value for attribute 
identified in previous longword 


2nd attribute ID code 


2nd attribute value 


End of list = 0 

(WDPL$C_END_OF_LIST) 


ZK-4581-85 


See the attributes argument in UIS$CREATE—WINDOW for more 
information. 
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UIS$EXPAND_ICON 


Screen Output 





USER 


ZK-5447-86 
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UIS$EXTRACT_HEADER 

Returns the header information needed to create a UIS metafile. 

Format 

UIS$EXTRACT_HEADER vdUd, [buflen, bufaddr] [,retlen] 

Returns 

UIS$EXTRACT_HEADER signals all errors; no condition values are returned. 


Arguments 

vd-Jd 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 

buflen 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Buffer length. The buflen argument is the address of a Iongword that defines 
the length of the buffer. 

bufaddr 

VMS Usage: vector—byte—signed 
type: byte integer (signed) 

access: read only 

mechanism: by reference 

Buffer address. The bufaddr argument is the address of an array of bytes 
that receives the binary encoding stream. 
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retlen 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write oniy 
by reference 


Return length. The retlen argument is the address of a longword that 
receives the length of the buffer. 


Description 

Header information must be at the beginning of all UlS metafiles. 

Allocating Space for the Buffer 

If you want to know how much space to allocate for the buffer, specify 
obj_id and retlen only. 

Format of Header Information 

The format of header binary instructions is as follows: 


Op code Length 

16 bits 16 bits 


Arguments 


ZK-5472-86 

If the length field exceeds 32,767 bytes, an extended format is used. The 
length field should be set to UIS$C_LENGTH_DIFF and the extra length 
field should be set to the total number of bytes in the binary instruction. 


Op code 

16 bits 

■B 

Extra Length 

32 bits 

Arguments 


ZK-5473-86 
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UIS$EXTRACT-_OBJECT 

Returns the binary encoding stream for the desired object (segment or 
primitive). 

Format 

UIS$EXTRACT_OBJECT | } [.buflen .bufaddr] 

[,retlen] 


Returns 

UIS$EXTRACT_OBJECT signals all errors; no condition values are returned. 

Arguments 

obj—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Object identifier. The obj_id argument is the address of a longword that 
uniquely identifies the object. 

seg—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Segment identifier. The seg—id argument is the address of a longword that 
uniquely identifies the segment. See UIS$BEGIN_SEGMENT for more 
information about the seg_id argument. 

buflen 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Length of buffer. The buflen argument is the address of a longword that 
specifies the length of the buffer that receives the binary encoding stream. 
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bufaddr 


VMS Usage: 
type: 
access: 
mechanism: 


vector_byte—unsigned 
byte (unsigned) 
read only 
by reference 


Name of an array. The bufaddr argument is the address of an array of bytes 
that receives the binary encoding stream. 


retlen 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Length of the binary encoding stream. The retlen argument is the address of 
a longword that receives the length of the binary encoding stream. 


Description 

If you want to know how much space to allocate for the buffer, specify 
obj.^d and retlen only. 

If the extracted object lies within a segment, a binary instruction denoting 
the beginning of the segment precedes all binary instructions associated with 
the extracted object. A binary instruction denoting the end of the segment 
follows the binary instructions associated with the extracted object. 
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UIS$EXTRACT_PRIVATE 

Returns the binary data associated with the specified object. 


Format 

UIS$EXTRACT_PRIVATE | .bufaddr] 

[,retlen] 


Returns 

UIS$EXTRACT_PRIVATE signals all errors; no condition values are returned. 


Arguments 

obj—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Object identifier. The obj_id argument is the address of a Iongword that 
uniquely identifies an object. 

seg—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Segment identifier. The seg_id argument is the address of a Iongword that 
uniquely identifies the segment. See UIS$BEG1N_SEGMENT for more 
information about the seg—id argument, 

buflen 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Length of the buffer. The buflen argument is the address of a Iongword that 
contains the length of the buffer that receives the binary encoding stream. 
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UIS$EXTRACT_PRIVATE 


bufaddr 


VMS Usage: 
type: 
access: 
mechanism: 


vector_byte—unsigned 
byte (unsigned) 
read only 
by reference 


Buffer address. The bufaddr argument is the address of an array of bytes 
that receives the binary encoding stream. 


retlen 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Length of the binary encoding stream. The retlen is the address of longword 
that receives the length of the binary encoding stream. 


Description 

If more than one private data item is associated with the specified object, all 
private data items are returned. The following figure describes the format of 
the data. If you want to know how much space to allocate for the returned 
encoding, specify the obj—id and retlen arguments only. 

Format of a Private Data Binary Instruction 

The format of binary encoding returned is as follows: 


Op code 

16 bits 


ATB 

16 bits 

Arguments 


ZK-5475-86 


If the length field exceeds 32,767 bytes, an extended format is used. The 
length field should be set to UIS$C_LENGTH_DIFF and the extra length 
field should be set to the total number of bytes in the binary instruction. 
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Attribute modification instructions precede the binary instruction of the 
extracted object. The binary instructions of any private data associated with 
the extracted object follow the binary instruction of the extracted object. 
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UIS$EXTRACT_REGION 

Locates all output primitives and portions of output primitives that lie 
entirely within the specified rectangle, and returns the binary encoding 
stream for the selected display. 


Format 

UIS$EXTRACT_REGION vd-id [,Xpyp X2,y2l [,buflen 

,bufaddr] [,retlen] 


Returns 

UIS$EXTRACT_REGION signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


Xi,yi,x2,y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the specified rectangle. The \\,y\ and XirJi arguments 
are the addresses of f—floating point numbers that define the lower-left and 
upper-right comers of the specified rectangle. 

If you specify a region within the virtual display, UIS$EXTRACT—REGION 
returns the entire display list except for the following: 

• Objects that do not lie completely within the specified region 

• Segments that do not contain any objects that fall completely within the 
specified region 
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If these arguments are not specified, the coordinates of the entire virtual 
display are used. 


buflen 


VMS Usage; 
type: 
access; 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Length of a buffer. The buflen is the address of a longword that contains the 
length of the buffer that receives the binary encoding stream. 


bufaddr 


VMS Usage: 
type: 
access: 
mechanism: 


vector_byte—unsigned 
byte—unsigned 
read only 
by reference 


Buffer address. The bufaddr argument is the address of an array of bytes 
that receives the binary encoding stream. 


retlen 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Length of the binary encoding stream. The retlen argument is the address of 
a longword that receives the length of the binary encoding stream. 


Description 

If you want to know how much space to allocate for the returned encoding, 
do riot specify the buflen and bufaddr arguments. 

Format of Binary Instructions 

The format of binary instructions is as follows: 


Op code Length 

16 bits 16 bits 


Arguments 


ZK-5472-86 
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If the length field exceeds 32,767 bytes, an extended format is used. The 
length field should be set to UIS$C_LENGTH_DIFF and the extra length 
field should be set to the total number of bytes in the binary instruction. 



Op code 
16 bits 


:h 

ts 


Extra Length 
32 bits 


Arguments 
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UIS$EXTRACT_TRAILER 

Returns trailer information needed to create a UIS metafile. 

Format 

UIS$EXTRACT_TRAILER vd—id[,buflen, bufaddr] [,retlen] 

Returns 

UIS$EXTRACT_TRAILER signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd—id argument. 

buflen 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Buffer length. The buflen argument is the address of a longword that defines 
the length of the buffer. 

bufaddr 

VMS Usage: vector—byte—signed 
type: byte integer (signed) 

access: read only 

mechanism: by reference 

Buffer address. The bufaddr argument is the address of an array of bytes 
that receive the binary encoded stream. 
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retlen 


VMS Usage; 
type: 
access; 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Return length. The retlen argument is the address of a longword that defines 
the returned length of the buffer. 


Description 

Trailer information must appear at the end of all UIS metafiles. 

Allocating Space for the Buffer 

If you want to know how much space to allocate for the buffer, specify 
obj_id and retlen only. 

Format of Trailer Information 

The format of trailer binary instructions is as follows; 


Op code Length 

16 bits 16 bits 


Arguments 


ZK-5472-86 


If the length field exceeds 32,767 bytes, an extended format is used. The 
length field should be set to UIS$C_LENGTH_DIFF and the extra length 
field should be set to the total number of bytes in the binary instruction. 


Op code 

16 bits 

Length 

16 bits 

Extra Length 

32 bits 

Arguments 


ZK-5473-86 
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UIS$FIND_PRIMITIVE 


Locates the next output primitive that intersects the specified rectangle. 


Format 

Oity^/cy=UIS$FIND«.PRIMITIVE vdUd, x^yp [,context] 

[, extent] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the object identifier in the variable obj^id or 
RO (VAX MACRO). The object identifier uniquely identifies the object and is 
used as an argument in other routines. 

UIS$FIND_PRIMITIVE signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_jd argument. 


Xpyi,x2,y2 
VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


World coordinates of the selection rectangle. The and X 2 ,y 2 are the 
addresses of f—floating points numbers that define the lower-left and upper- 
right comers of the rectangle. 
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context 


VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 

modify 

by reference 


Context value. The context argument is the address of a longword that stores 
the state of the search and should not be modified if repetitive searches are 
desired. If this argument is omitted, only the first match can be found in the 
display list. 

You must initialize the context argument to 0 before starting a search 
operation. 


extent 


VMS Usage: 
type: 
access: 
mechanism: 


vector_iongword—unsigned 
iongword (unsigned) 
write only 
by reference 


Address of the extent rectangle array. The extent argument is an array of 
four longwords that receives the world coordinate values of the lower-left 
and upper-right comer of the extent rectangle. 


Description 

When you try to locate the specified object closest to the specified location, 
the size of the rectangle controls the object or primitive matching granularity. 
Normally, when you search for the primitive nearest a position, the rectangle 
would surround the position, and have a small width and height (perhaps 
equivalent to 1 to 10 pixels), depending on the desired granularity. 

Once the primitive is located, it returns an object identifier which can be 
used later to reference the primitive, for example, UIS$EXTRACT_OBJECT or 
UIS$DELETE_OBJECT. 

Each time UIS$FIND_JPRIMITIVE is called, it continues the search operation 
from where it left off, using the context longword to keep track of the current 
state. 

Generally, in order to find all matches, UIS$FIND_PRIMITIVE is called 
repeatedly with the same context longword until it returns a value of 0. 
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UIS$FIND_SEGMENT 

Locates the next segment that contains any objects or primitives that intersect 
with the specified rectangle. 


Format 

se5f_/c/=UIS$FlND_SEGMENT vd—id, Xp yp x^, [,context] 

[, extent] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
write oniy 
by vaiue 


Longword value returned as the segment identifier in the variable seg—id or 
RO (VAX MACRO). The segment identifier uniquely identifies the segment 
and is used as an argument in other routines. 

UIS$F1ND_SEGMENT signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


xi,ypX2,y2 
VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read oniy 
by reference 


World coordinates of the selection rectangle. The Xpji and X 2 ,y 2 arguments 
are the addresses of f—floating point numbers that define the lower-left and 
upper-right comers of the rectangle. 
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context 


VMS Usage: 
type: 
access: 
mechanism: 


context 

longword (unsigned) 

modify 

by reference 


Context value. The context argument is the address of a longword that stores 
the state of the search and should not be modified if repetitive searches are 
desired. If this argument is omitted, only the first match can be found in the 
display list. 

You must initialize the context argument to 0 before starting a search 
operation. 

extent 

VMS Usage: vector_longword—unsigned 
type: iongword (unsigned) 

access: write only 

mechanism: by reference 

Address of the extent rectangle array. The extent argument is the address 
of an array of four longwords that receives the world coordinate pairs 
that define the lower-left and upper-right comers of the extent rectangle 
containing the segment. 


Description 

The size of the rectangle controls the matching granularity when trying to 
locate the primitive closest to a specific position. Normally, when searching 
for the primitive nearest a position, the rectangle would surround the 
position, and have a small width and height (perhaps equivalent to 1 to 
10 pixels), depending on the desired granularity. 

Once the object is located, UIS$FIND_SEGMENT returns the object identifier 
for the segment containing that object. 

Each time this routine is called, it continues the search operation from where 
it left off, using the context longword to keep track of the search state. 

Generally, in order to find all matches, UIS$FIND_SEGMENT is called 
repeatedly with the same context longword until it returns a value of 0. 
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UIS$GET_JVBS_POINTER^POS 

Returns the current pointer position relative to the lower-left comer of the 
workstation screen. 


Format 

UIS$GET-_ABS_POINTER_POS devnam, retx, rety 


Returns 

UIS$GET_ABS_POINTER_POS signals all errors; no condition values are 
returned. 


Arguments 


devnam 

VMS Usage: 
type: 
access: 
mechanism: 


device^ame 
character string 
read only 
by descriptor 


Device name string. The devnam argument is the address of a character 
string descriptor of the workstation device name. Specify the logical name 
SYS$WORKSTATION as the device name string. 


retx, rety 
VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Absolute device coordinate pair. The retx and rety arguments are the 
addresses of f—floating point longwords that receive the x and y coordinate 
positions of the pointer in centimeters relative to the lower-left comer of the 
display screen. 
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UIS$GET^LIGNED-POSITION 

Returns the current position for text output which is the upper-left comer of 
the character cell. 


Format 

UIS$GET_ALIGNED^POSITION vd-id, atb, retx, rety 


Returns 

UIS$GET_ALIGNED_POSITION signals all errors; no condition values are 
returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block. The atb argument is the address of a longword integer that 
identifies an attribute block that contains the font to use in calculating the 
aligned position. 


retx, rety 
VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 
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World coordinate pair. The retx and rety arguments are the addresses of 
f_floating point longwords that receive the current position as x and y world 
coordinate positions. 

Description 

UIS$GET_ALIGNED_POSITION differs from UIS$GET_POSITION in that 
the current position refers to the upper-left comer of the character cell of the 
next character to be output. This is useful for applications that require the 
position of the upper-left comer, but do not know enough about the font 
baseline to determine the proper alignment point. The position is converted 
into the proper alignment point using the font specified in the given attribute 
block. See UIS$SET_ALIGNED_POSITION. 


Screen Output 


$ run get_alisned 

X world coordinate =18.19 y world coordinate = 5.02 

FORTRAN PAUSE 



Text Alignment Current position 

Point after text 

drawing 
( 18 . 19 , 5 . 02 ) 


ZK.5293-86 




















18-100 UlS Routine Descriptions 
UIS$GET_ARC_TYPE 


UIS$GET_ARC_TYPE 

Returns the current arc type attribute code. See UIS$SET_ARC_TYPE for 
more information about arc types. 


Format 

arc_fype=UIS$GET^RC_TYPE vd-id, atb 


Returns 


VMS Usage; 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by value 


Longword value returned as the current arc type code in the variable 
arc—type. The arc type code is an integer value representing one of the 
following UIS constants: UIS$C_ARC_OPEN, UIS$C_-ARC—PIE, and 
UIS$C_ARC_CHORD. See UIS$SET_ARC_TYPE for a description of the 
constants. 


UIS$GET_ARC_TYPE signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block identifier. The atb argument is the address of a longword 
integer that identifies the attribute block from which the arc type is obtained. 
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Description 

Refer to Section 6.6 for more information about UIS symbols and symbol 
definition files. 
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UIS$GET^BACKGROUND_INDEX 

Returns the background color index for text and graphics output. 


Format 

/ncfexHJIS$GET-.BACKGROUND_INDEX vdUd, atb 


Returns 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as the color map index in the variable index or RO 
(VAX MACRO). 

UIS$GET_BACKGROUND_INDEX signals all errors; no condition values are 
returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

atb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a longword 
integer that identifies the attribute block from which the background color 
index is obtained. 
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UIS$GET_BUTTONS 


Returns the current state of the pointer buttons. 


Format 

sfafas=UIS$GET_BUTTONS wd—id, retstate 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


boolean 

longword (unsigned) 
write only 
by value 


Boolean value is returned in the variable status or RO (VAX MACRO). A value 
of 1 is returned, if the pointer is within the visible portion of the viewport. 

If the pointer is outside the visible portion of the viewport, a value of 0 is 
returned. 


UIS$GET_BUTTONS signals all errors; no condition values are returned. 


Arguments 


wd—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


retstate 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
write only 
by reference 


State of the pointer buttons. The retstate argument is the address of a 
longword that receives the current state of the pointer buttons. The state 
of pointer buttons is returned in a longword whose bits indicate the state 
of each pointer button, for example, 1 is up and 0 is down. The symbolic 
definitions for these bits are UIS$M_POINTER_BUTTON_l, and UIS$M_ 
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POINTER_BUTTON_2, UIS$M-POINTER-BUTTON_3, and 
UIS$M-POINTER-BUTTON-4. 


Description 

The returned status value should always be tested when using this function, 
because it is always possible that the pointer could be outside the window 
when the function is called. 
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UIS$GET_CHAR_ROTATION 


Returns the angle of character rotation in degrees. 


Format 

a/7gf/e=UIS$GET_CHAR_ROTATION vd-id, atb 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by value 


Longword value returned as the angle of character rotation in degrees in the 
variable angle or RO (VAX MACRO). The baseline vector and the actual path 
of text drawing form the angle of character rotation. The character rotates on 
its baseline point. 

UIS$GET—CHAR—ROTATION signals all errors; no condition values are 
returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read oniy 
by reference 


Attribute block number. The atb argument is the address of a number that 
identifies an attribute block containing the character rotation attribute used to 
calculate character rotation. 
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UIS$GET_CHAR_SIZE 

Returns both a value indicating whether or not character scaling is enabled 
and the character size used. 


Format 

/?oo/ean=UIS$GET_CHAR_SIZE vd-id, atb 

,[char],[width][,height] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


boolean 

longword (unsigned) 
write only 
by value 


Boolean value returned to indicate the status of character scaling in a status 
variable or RO (VAX MACRO). 

UIS$GET_CHAR_SIZE signals all errors; no condition values are returned. 


Arguments 


vd-id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE_DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block that contains the character size attribute setting. 
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char 

VMS Usage: char_string 
type: character_string 

access: write only 

mechanism: by descriptor 

Single character. The char argument is the address of a character string 
descriptor of a single char. The char is specified only for proportionally 
spaced fonts. It is used as a reference point against which other characters 
are scaled. 

width 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Character width. The width argument is the address of an f_floating point 
longword that receives the character width in world coordinates. 

height 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Character height. The height argument is the address of an f—floating point 
longword that receives the character height in world coordinates. 
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UIS$GET_CHAR_SLANT 

Returns the angle of character slant in degrees. 

Format 

an 5 f/e=UIS$GET_CHAR_SLANT vd-id, atb 

Returns 

VMS Usage: floating-point 
type: f—floating 

access: write oniy 

mechanism: by value 

Longword value returned as the angle of character slant in degrees in the 
variable angle or RO (VAX MACRO). The character cell up vector and the 
baseline vector form the angle of character slant. 

U1S$GET_CHAR_SLANT signals all errors; no condition values are 
returned. 


Arguments 

vdL/d 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vcLid argument is the address of a longword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd—id argument. 

atb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a number that 
identifies an attribute block containing the character slant attribute setting to 
be returned. 
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Screen Output 


$ run get_charslant 

The angle of character slant is 

FORTRAN PAUSE 

i 


35.00 degrees 
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UIS$GET^CHAR_SPACING 

Returns the character spacing factors. 

Format 

UIS$GET_CHAR_SPACING vd-id, atb, dx, dy 
Returns 

UIS$GET_CHAR_SPAGING signals all errors; no condition values are 
returned. 


Arguments 

vdUd 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vdL_id argument is the address of a longv^ord 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

atb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a longv^ord 
integer that identifies the attribute block from which the character spacing 
factors are obtained. 

dx 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Additional x spacing factor. The dx argument is the address of an f—floating 
point Iongword that receives the x spacing factor. The x spacing factor 
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represents the relative width of the character cell. If 0 is returned, no 
additional spacing factor was specified. 

dy 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Additional y spacing factor. The dy argument is the address of an f—floating 
point longword that receives the y spacing factor. The y spacing factor 
represents the relative height of the character cell. If 0 is returned, no 
additional spacing factor was specified. 


Screen Output 


$ run get_charspace 
X spacing factor = 0.00 
X spacing factor = 3.00 
X spacing factor = 0.00 
X spacing factor = 4.00 
FORTRAN PAUSE 

k I 


y 

spacing 

factor = 

0. 

00 

y 

spacing 

factor = 

5. 

00 

y 

spacing 

factor = 

0. 

00 

y 

spacing 

factor = 

6 . 

00 



Great vits Imave short memories 
Great wits 


Never spur a willing horse 
Never s p 
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UIS$GET_CLIP 

Returns the clipping mode. 

Format 

sfaft/s=UIS$GET_CLIP vdUd, atb [,Xp yp x^, 

Returns 

VMS Usage: boolean 
type: longword 

access: write only 

mechanism: by value 

Boolean value returned as the clipping mode in a status variable or RO (VAX 
MACRO). If clipping is enabled, a boolean TRUE is returned. If clipping is 
disabled, a boolean FALSE is returned. 

UIS$GET_CLIP signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd-id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

atb 

VMS Usage: longword-unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a longword 
integer that identifies the attribute block from which the clipping rectangle 
and mode are obtained. 
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Xi, Yi, X2, y2 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


World coordinate pair. The Xj and arguments are addresses of f_floating 
point longwords that receive the coordinates of the lower-left comer of 
the world coordinate clipping rectangle. The X2 and y2 arguments are the 
addresses of f_floating point longwords that receive the coordinates of the 
upper-right comer of the world coordinate clipping rectangle. 
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Screen Output 


$ run get.clip 

Is clipping enabled? F = FALSE T = TRUE 
F 

FORTRAN PAUSE 

I_ 



FORTRAN PAUSE 
$ cent 

Is clipping enabled? F = FALSE T = TRUE 
T 

FORTRAN PAUSE 

$ 
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UIS$GET_COLOR 

Returns a single red green blue (RGB) color value associated with an entry in 
a virtual color map. 


Format 

UIS$GET_COLOR vd—id, index, retr, retg, retb [,wd—id] 


Returns 

UIS$GET_COLOR signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 


index 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual color map index. The index argument is the address of a Iongword 
that specifies the index of the virtual color map entry to be returned. 

retr 

VMS Usage: floating—point 
type: f—floating 

access: write only 

mechanism; by reference 


Red value. The retr argument is the address of an f—floating point Iongword 
that receives the red value. The red value is in the range of 0.0 to 1 . 0 , 
inclusive. 
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retg 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f_floating 
write only 
by reference 


Green value. The retg argument is the address of an LJloating point 
longword that receives the green value. The green value is in the range 
of 0.0 to 1.0, inclusive. 


retb 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Blue value. The retb argument is the address of an f—floating point longword 
that receives the blue value. The blue value is in the range of 0.0 to 1.0, 
inclusive. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


object—id 
longword 
read only 
by reference 


Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies a display window. If this argument is 
specified, it must be a valid wd—id associated with the virtual display. The 
colors returned are the realized colors for the specific device for which the 
window was created. See UIS$CREATE—WINDOW for more information 
about the wd—id argument. 

If wd—id is not specified, the set color values, that is, the actual color values 
in the specified color map entry are returned. 
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Illustration 



Red Value 
Green Value 
Blue Value 


ZK-5444-86 
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UIS$GET_COLORS 

Returns red, green, and blue (RGB) color values associated with one or more 
entries in the virtual color map. 


Format 

UIS$GET_COLORS vd—id, index, count, retr—vector, 

retg—vector, retb—vector [, wd—id] 


Returns 

UIS$GET_COLORS signals all errors; no condition values are returned. 


Arguments 


vcL-id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE_D1SPLAY for 
more information about the vd_id argument. 


index 


VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Starting color map index. The index argument is the address of a Iongword 
that specifies the index of the first color map entry to be returned. 

If the specified index exceeds the maximum index for the virtual color map, 
an error is signaled. 


count 


VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 
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Number of virtual color map indices. The count argument is the address of 
a longword that defines the total number of color map entries in the virtual 
color map to be returned including the starting index. 

If the total number of indices exceeds the maximum number of indices in the 
virtual color, an error is signaled. 

retr^vector 

VMS Usage: vector_longword—signed 

type: f_floating 

access: write only 

mechanism: by reference 

Red values. The retr_vector argument is the address of an array of 
f_floating point longwords that receives the red color values. Each red value 
is in the range of 0.0 to 1.0, inclusive. 


retg—vector 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword—signed 
f_floating 
write only 
by reference 


Green values. The retg_vector argument is the address of an array of 
f_floating point longwords that receives the green color values. Each green 
value is in the range of 0.0 to 1.0, inclusive. 


retb—vector 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—signed 
f_floating 
write only 
by reference 


Blue values. The retb_vector argument is the address of an array of 
f__floating point longwords that receives the blue color values. Each blue 
value is in the range of 0.0 to 1.0, inclusive. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. If specified, the wd_id 
argument must be a valid display window identifier associated with the 
virtual display. See UIS$CREATE—WINDOW for more information about 
the wd—id argument. 
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The color values returned are the realized color values for the specific device 
for which the display window was created. 

If the wdLid argument is not specified, the red, green, and blue color values 
returned are the set color values originally established by UIS$SET_COLOR 
or UIS$SET_COLORS. 


Illustration 


Color Map 

• 


• 


• 

Index 

Red Value 


Green Value 


Blue Value 

4 

Red Value 


Green Value 


Blue Value 

5 

Red Value 


Green Value 


Blue Value 

6 

Red Value 


Green Value 


Blue Value 

7 

Red Value 


Green Value 


Blue Value 

8 

Red Value 


Green Value 


Blue Value 

9 

Red Value 


Green Value 


Blue Value 


• 


• 


• 


• 


• 


• 


• 


• 


• 


0.10 

0.20 

0.30 

0.40 

0.50 

0.60 

0.70 

0.80 

0.90 



ZK-5365-86 
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UIS$GET_CURRENT_OBJECT 

Returns the identifier of the last object drawn in the virtual display and 
added to the display list. 


Format 

curreA7f_/cf=UIS$GET_CURRENT--0BJECT vd-id 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write oniy 
by vaiue 


Longword value returned as the identifier of the current object in the variable 
current-id or RO (VAX MACRO). 

UIS$GET_CURRENT_OBJECT signals all errors; no condition values are 
returned. 


Argument 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


Description 

If there are no objects in the display list, the root segment identifier is 
returned. If UIS$GET_CURRENT_OBJECT is called after a call to UIS$SET_ 
INSERTION—POSITION, the returned identifier is based on the current 
insertion position in the segment. 
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Screen Output 

^ run get_currobj 

Identifier of current object = 114752 

FORTRAN PAUSE 

iJ 
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UIS$GET_DISPLAY_SIZE 

Obtains the dimensions of the workstation display screen. 

Format 

UIS$GET_DISPLAY_SIZE devnam, retwidth, retheight 

[,retresolx, retresoly] [,retpwidth, 
retpheight] 

Returns 

UIS$GET_DISPLAY_SIZE signals all errors; no condition values are returned. 

Arguments 

devnam 

VMS Usage; device_name 
type; character string 

access; read only 

mechanism; by descriptor 

Device name string. The devnam argument is the address of a character 
string descriptor of the workstation device name. Specify SYS$WORKSTATION 
as the device name character string. 

retwidth, retheight 
VMS Usage; fioating_point 
type; f_floating 

access; write only 
mechanism; by reference 

VAXstation display screen size. The retwidth and retheight arguments are 
the addresses of f_floating point longwords that receive the physical display 
screen width and height in centimeters. 

retresoix, retresoiy 
VMS Usage; floating-point 
type; f—floating 

access; write only 
mechanism; by reference 
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VAXstation display screen resolution. The retresolx and retresoly arguments 
are the addresses of f—floating point longwords that receive the x and y 
resolution in pixels per centimeters. 


retpwidth, retpheight 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write oniy 
by reference 


VAXstation screen size in pixels. The retpwidth and retpheight arguments 
are the addresses of integer longwords that receive the width and height of 
the screen in pixels. 


Description 

The height and width dimensions can be used when deciding the size of a 
virtual display or viewport. The resolution values can be used when it is 
important for the application to determine the exact physical size (or world 
coordinate dimensions) that map to a single pixel. 
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Screen Output 

$ run get_display 

Display screen characteristics 

width = 33.58 cm height = 28.34 cm 

X resolution = 30.49 pixels/cm 

y resolution = 30.49 pixels/cm 

width = 1024 pixels height = 864 pixels 

FORTRAN PAUSE 

1 ^ ■ _ 
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UIS$GET_FILL -PATTERN 

Returns the index of the fill pattern. 

Format 

sfafus=UIS$GET_FILL-PATTERN vd-id, atb [,index] 

Returns 

VMS Usage: boolean 
type: longword 

access: write only 

mechanism: by value 

Boolean value returned as the filling mode in a status variable or RO (VAX 
MACRO). The boolean TRUE is returned if filling is enabled, otherwise the 
boolean value is FALSE. 

U1S$GET_PILL-PATTERN signals all errors; no condition values are 
returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

atb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a longword 
integer that identifies the attribute block from which the fill pattern index is 
obtained. 
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index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Index of the fill pattern. The index argument is the address of a longword 
that receives the value of the fill pattern symbol index. This is the index of a 
glyph in a fill pattern font. 
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UIS$GET__FONT 

Returns the name of font file. 


Format 

UIS$GET_FONT vd-id, atb, bufferdesc [,length] 


Returns 

UIS$GET_FONT signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies the attribute block from which the font file name is 
obtained. 


bufferdesc 


VMS Usage: 
type: 
access: 
mechanism: 


char—string 
character string 
write only 
by descriptor 


Font file name string. The bufferdesc argument is the address of a character 
string descriptor of a location that receives the font file name character string. 
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length 

VMS Usage: word—signed 
type: word (signed) 

access: write only 

mechanism: by reference 

Length of the font file character string. The length argument is the address 
of a word that receives the length of font file name character string. 


Screen Output 

$ run get^fontname 

font name is DTABER0R07SK00GG0001UZZZZ02A000 
length of font name is 31 characters 

FORTRAN PAUSE 

k I 



The more the merrier 
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UIS$GET_FONT_ATTRIBUTES 

Returns information about the ascender, descender, height, width, and font 
parameters. 


Format 

UIS$GET_FONT_ATTRIBUTES 


font—id, ascender, 
descender, height 
[,maximum—width] [item—list] 


Returns 

UIS$GET__FONT_ATTRIBUTES signals all errors; no condition values are 
returned. 


Arguments 


font—id 


VMS Usage: 
type: 
access: 
mechanism: 


Char-String 
character string 
read only 
by descriptor 


Font file name. The font—id argument is the address of a string descriptor 
of the font file name only. UIS searches the directory SYS$FONT for the 
correct file type. 


ascender 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Character ascender. The ascender argument is the address of a longword 
that receives the distance between the font baseline and the top of the 
character cell in pixels. 


descender 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 
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Character descender. The descender argument is the address of a longword 
that receives the distance between the font baseline and the bottom of the 
character cell in pixels. 

height 

VMS Usage: longword-unsigned 
type: longowrd (unsigned) 

access: write only 

mechanism: by reference 

Height of the character cell. The height argument is the address of a 
longword that receives the height of the character cell in pixels. 

maximum-width 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Maximum width of a character cell. The average-width argument is the 
address of a longword that receives the maximum width of a character cell in 
the font in pixels. 

item—iist 

VMS Usage: item—list—3 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Item list specifying additional font information to be returned. The item—list 
argument is the address of a list of item descriptors, each of which describes 
an item of information. A longword value of 0 terminates the list of item 
descriptors. 

The structure of the item list is described in the following figure. 

31 15 0 



ZK-1705-84 









UlS Routine Descriptions 18-133 
UIS$GET_FONT_-ATTRIBUTES 


The following table lists valid item codes. 

Item Code Information Returned 

Character Information 

UIS$C_FNT_FIRST_CHAR First character in the font 

UIS$C_FNT_LAST_CHAR Last defined character in the font 

UIS$C_FNT_GUTPERPIX_X x resolution of the font in gutenbergs per pixel 

UIS$C_FNT_GUTPERPIX_Y y resolution of the font in gutenbergs per pixel 

UIS$C_FNT_AVERAGE_GUT^ Average width of a character in the font 

UIS$C_-FNT_WIDTH Width in pixels of all glyphs in the font, if the 

font is monospaced. A zero is returned, if the 
font is proportionally spaced. 

Font Flags^ 

UIS$C-JFNT_FIXED 

UIS$C_FNT_CELLEQRAST 
UIS$C_FNT_VA_FONT 

Font Name 

UIS$C_FNT_FONT_ID Font identifier string 

^The font designer assigns this number. Although, the graphics subsystem copies the number, 
no interpretation is applied to it. UIS does not use the number. 

^The value 1 is returned, if TRUE, and 0, if FALSE. 


True, if the font is monospaced 

False, if the font is proportionally spaced. 

True, if the cell width of all glyphs in the font 
equals the width the glyph's raster. 

True, if this is a VA font. 
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UIS$GET_FONT_SIZE 

Obtains the size of a character or string of characters in the specified font in 
physical dimensions. 


Format 

UIS$GET_FONT_SIZE fontid, text—string, retwidth, retheight 


Returns 

UIS$GET_FONT_SIZE signals all errors; no condition values are returned. 


Arguments 


fontid 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Font identifier. The fontid argument is the address of a character string 
descriptor of a font file name. Specify only the font file name. UlS searches 
the directory SYS$FONT for the correct file type. 


text—String 
VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Text string. The text—string argument is the address of a descriptor of a 
character or character string. 


retwidth, retheight 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


String width and height. The retwidth and retheight arguments are the 
addresses of f—floating point longwords that receive the width and height of 
the character or character string in centimeters. 
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Description 

UIS$GET_FONT_SIZE can be used to determine the proper size of a display 
viewport based on the size of the characters in a given font. 


Screen Output 


$ run get__fontsize 
string length = 11.01970 cm 

character height = 0.4919507 cm 

FQRTRRN PRUSE 



l^^llllllllllllllllillillllllllllllllllillllllllllilllllllllllllllllllllllllll^ 


Ba.dl news “bimvels fe.s'fc 


ZK-5283-86 
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UIS$GET_HW__COLORJNFO 


Returns information about the hardware color map. 


Format 

UIS$GET_HW__COLOR_INFO devnam [,type] [,indices] 

[,coiors] [,maps] [,rbits] [,gbits] 
[,bbits] [,ibits] [,res—indices] 

[,regen] 


Returns 

UIS$GET_HW_COLOR_INFO signals all errors; no condition values are 
returned. 


Arguments 

devnam 

VMS Usage: device—name 
type: character string 

access: read only 

mechanism: by descriptor 

Device name. The devnam argument is the address of a character string 
descriptor of the workstation device name. Specify SYS$WORKSTATION in 
the devnam argument. 


type 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Device type. The type argument is the address of a longword that receives 
the device type. The following table lists device type values. 
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Device Type 

Value 

Possible 

Colors 

Monochrome 

UIS$C_DEV_MONO 

Black and white 

Intensity 

UIS$C_DEV_INTENSITY 

Up to 2^^ gray tones 

Color 

UIS$C_DEV_COLOR 

Up to 2^^ chromatic colors 

indices 



VMS Usage: 

longword—unsigned 


type: 

longword (unsigned) 


access: 

write oniy 


mechanism: 

by reference 



Number of entries or simultaneous colors. The indices argument is the 
address of longword that receives the number of entries or simultaneous 
colors in the hardware color map. 


colors 


VMS Usage; 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Number of possible colors. The colors argument is the address of a longword 
that receives the number of possible colors represented in the color map. For 
example monochrome equals 2. 


maps 

VMS Usage: 
type: 
access; 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Number of hardware color maps. The maps argument is the address of a 
longword that receives the number of hardware color maps. 


rbits 


VMS Usage: 
type: 
access; 
mechanism: 


longword—unsigned 
longword (unsigned) 
write oniy 
by reference 


Number of binary bits of precision for red. The rbits argument is the address 
of a longword that receives the number of binary bits of precision for the 
color red. 
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gbits 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Number of binary bits of precision for green. The gbits argument is the 
address of a longword that receives the number of binary bits of precision for 
the color green. 


bbits 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Number of binary bits of precision for blue. The bbits argument is the 
address of a longword that receives the number of binary bits of precision for 
the color blue. 


ibits 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Number of binary bits of precision for intensity. The ibits argument is the 
address of a longword that receives the number of binary bits of precision for 
intensity. 


res—indices 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Number entries in the hardware color map reserved for special use. The 
res—indices argument is the address of a longword that receives the number 
entries in the hardware color map reserved for special use. 


regen 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Color regeneration characteristics. The regen argument is the address of 
a longword that receives the color regeneration characteristics. The regen 
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argument indicates whether the color and intensity changes affect previously 
drawn display objects that specified the same color index in the hardware 
look up table. The following symbols are valid values: UIS$C_DEV__RETRO 
or UIS$C_DEV_NONRETRO. 

The following table summarizes regeneration characteristics of direct and 
mapped color systems. 


System 
Direct color 
Mapped color 


Regeneration Characteristics 

Usually sequential 
Usually retroactive 
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UIS$GET^INTENSITIES 

Returns intensity values associated with one or more entries in the virtual 
color map. 

Format 

UIS$GET_INTENSITIES vd—id, index, count, reti—vector 

[,wd—id] 

Returns 

UIS$GET_INTENSITIES signals all errors; no condition values are returned. 


Arguments 

vdJid 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

index 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Starting color map index. The index argument is the address of a longword 
that specifies the index of the first color map entry to be returned. If the 
specified index exceeds the maximum index of the virtual color map, an error 
is signaled. 

count 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 
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Number of indices. The count argument is the address of a longword that 
specifies the total number of color map entries to be returned including the 
starting index. If the specified count exceeds the maximum number of virtual 
color map entries, an error is signaled. 


reti—vector 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—signed 
f—floating 
write only 
by reference 


Intensity values. The reti—vector argument is the address of an array of 
f—floating point longwords that receives the intensity values. Each intensity 
value is in the range of 0.0 to 1.0, inclusively. 


wd-Jd 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies a display window. If the wd—id argument 
is specified, it must be a valid display window identifier associated with the 
virtual display. The returned values are the realized intensities for the specific 
device for which the display window was created. See UIS$CREATE— 
WINDOW for more information about the wd—id argument. 

If the wd—id argument is not specified, the intensity values returned are 
set color values originally established by a call to UIS$SET—INTENSITY or 
UIS$SET_INTENSITIES. 
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illustration 
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UIS$GET_INTENSITY 

Returns the intensity value associated with a single entry in the color map. 

Format 

UIS$GETINTENSITY vd-id, index, reti, [,wd-id] 

Returns 

U1S$GET_INTENSITY signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd—id argument. 

index 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Color map index. The index argument is the address of a Iongword integer 
that identifies the index of an entry in the color map associated with the 
virtual display. If the specified index exceeds the maximum number of 
indices in the virtual color map, an error is signaled. 

reti 

VMS Usage: fioating—point 
type: f—floating 

access: write oniy 

mechanism: by reference 

Intensity value. The reti argument is the address of an f—floating point 
Iongword that receives the intensity value. The intensity value is in the 
range of 0.0 to 1.0, inclusive. 
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wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wdLid is the address of a Iongword that 
uniquely identifies the display window. See UIS$CREATE—WINDOW for 
more information about the wd_id argument. If this argument is specified, it 
must be a valid wd—id associated with the virtual display, and the returned 
values are the realized intensities for the specific device for which the window 
was created. 

If the wd—id argument is not specified, the returned intensity values are 
set intensity originally established by a call to UIS$SET_INTENSITY or 
UIS$SET_INTENSITIES. 


Illustration 



ZK-5446-86 
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UIS$GET_KB->ATTRIBUTES 


Returns the virtual keyboard characteristics. 


Format 

UIS$GET_KB_ATTRIBUTES kb-id [,enable-items] 

[, disable—items][, click— volume] 


Returns 

UIS$GET_KB_ATTRIBUTES signals all errors; no condition values are 
returned. 


Arguments 


kb—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual keyboard identifier. The kb—id argument is the address of a 
Iongword that uniquely identifies the virtual keyboard. See 
UIS$CREATE_KB for more information about the kb—id argument. 


enable—items 

VMS Usage: mask—iongword 
type: iongword (unsigned) 

access: write oniy 

mechanism: by reference 


Enabled keyboard characteristics. The enable—items argument is the address 
of a Iongword mask that receives the bit mask of the enabled keyboard 
characteristics. 


disable—items 

VMS Usage: mask—iongword 
type: iongword (unsigned) 

access: write oniy 

mechanism: by reference 
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Disabled keyboard characteristics. The disable—items argument is the 
address of a longword mask that receives the bit mask of the disabled 
keyboard characteristics. 

click—volume 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Key click volume level. The click—volume argument is the address of a 
longword that receives the key click volume level. The key click volume is 
in the range of 1 to 8, inclusively, where 1 is quiet and 8 is loud. 


Description 

The enable and disable item lists are longword masks containing bits 
designating the characteristics to be enabled or disabled. The valid bits 
in the keyboard characteristics enable and disable masks are: 


Symbol 

Description^ 

UIS$M_KB_AUTORPT 

Enable/disable keyboard autorepeat 

UIS$M_KB_KEYCLICK 

Enable/disable keyboard keyclick 

UIS$M_KB_UDF6 

Enable/disable up button transitions for HI] to Ifio| keys 

UIS$M_KB_UDF11 

Enable/disable up button transitions for |F11 1 to 
|F14| keys 

UIS$M_KB_UDF17 

Enable/disable up button transitions for |F17| to 
|F20| keys 

UIS$M_KB_HELPDO 

Enable/disable up button transitions for 1 help I and 
|DO| keys 

UIS$M_KB_UDE1 

Enable/disable up button transitions for HU to [Ml keys 

UIS$M_KB_ARROW 

Enable/disable up button transitions for arrow keys 

UIS$M_KB_KEYPAD 

Enable/disable up button transitions for numeric 
keypad keys 

^By default down button transitions are enabled. 
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UIS$GET_LINE^STYLE 

Returns the line style patterns. 

Format 

sty/e=UIS$GET_LINE_STYLE vd-id, atb 

Returns 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as the line style bit vector in the variable style or 
RO (VAX MACRO). 

UIS$GET_L1NE—STYLE signals all errors; no condition values are returned. 

Arguments 

vd^id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd—id argument. 

atb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block from which the line style pattern or 
bit vector is obtained. 
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Screen Output 


$ run get^linestyle 
line no.1 style = FOFOFOFO 

line no.2 style = FOOFOOFO 

line no.3 style = COCOCOCO 

FORTRRN PRUSE_ 
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UIS$GET_LINE-WIDTH 

Returns the line width. 

Format 

M^/cyfA7=UIS$GET_LINE_WIDTH vd-id, atb [,mode] 

Returns 

VMS Usage; floating-point 
type: f—floating 

access: write only 

mechanism: by value 

F_floating point value returned as the line width in the variable width or RO 
(VAX MACRO). 

UIS$GET_L1NE—WIDTH signals all errors; no condition values are returned. 

Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

atb 

VMS Usage: longword-unsigned 
type: Iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Attribute block number. The atb argument is the address of a Iongword 
integer that identifies the attribute block from which the line width is 
obtained. 







UlS Routine Descriptions 18-151 

UIS$GET-LINE-WIDTH 


mode 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Line width mode. The optional mode argument is the address of a longword 
that receives the line width specification mode (WDPL$C_WIDTH_WORLD 
or WDPL$C_WIDTH_PIXELS). If WDPL$C_WIDTH_WORLD is returned, 
the line width is interpreted as world coordinates. If WDPL$C_WIDTH_ 
PIXELS is returned, the line width is interpreted as pixels. 
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UIS$GET_NEXT_OBJECT 


Returns the identifier of the next object in the display list. 


Format 

nexf_W=UIS$GET_NEXT_OBJECT | } [.flags] 

V f J 


Returns 

VMS Usage: identifier 
type: iongword (unsigned) 

access: write oniy 

mechanism: by reference 

Longword value returned as the next object identifier in the variable 
next—id or RO (VAX MACRO). The next object identifier uniquely identifies 
the next specified object in the display list and is used as an argument in 
other routines. 

UIS$GET_NEXT_OBJECT signals all errors; no condition values are returned. 


Arguments 


obi—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Object identifier. The obj-Jd argument is the address of a longword that 
uniquely identifies the object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg—id argument is the address of a longword that 
uniquely identifies the segment. 
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flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
read only 
by reference 


Flags. The flags argument is the address of a longword that controls how 
the display list is searched. If the flags argument is set using UIS$M_DL_ 
SAME—SEGMENT, the next object in the segment containing the object 
specified is returned. 

If the flags argument is omitted, the next object in the display list, regardless 
of the segment in which it is contained, is returned. 


Description 

If a zero is returned, the next object was not found. 
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UIS$GET_OBJECT_ATTRIBUTES 

Returns the type and extent of the specified object. 

Format 

fype=UlS$GET_OBJECT_ATTRIBUTES | \ [.extent] 

v — / j 


Returns 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as the object type in the variable type or RO (VAX 
MACRO). An object type identifies a graphic object such as images, points 
lines, or ellipses, a display list structure such as a segment, or the occurrence 
of an event such as movement to a new text line. Possible valid objects are 
listed in the follo^ving table. 


Symbol 

Description 

UIS$C_OBJECT_SEGMENT 

Segment 

UIS$C_OBJECT_PLOT 

Point, line, connected lines, or polygon 

UIS$C_OBJECT_TEXT 

Characters 

UIS$C_OBJECT_ELLIPSE 

Elliptical or circular arcs, circles and ellipses 

UIS$C_OBJECT_IMAGE 

Raster image 

UIS$C_OBJECT_LINE 

Unconnected lines 


UIS$GET_OBJECT_ATTRlBUTES signals all errors; no condition values are 
returned. 


Arguments 

obj—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 
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Object identifier. The obj—id argument is the address of a longword that 
uniquely identifies the object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg—id argument is the address of a longword that 
uniquely identifies the segment. See UIS$BEGIN—SEGMENT for more 
information about the seg—id argument. 


extent 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—signed 
f—floating 
write only 
by reference 


World coordinates of the extent rectangle. The extent argument is the 
address of an array of four longwords that receives the values of the world 
coordinates of the lower-left comer and the upper-right comer of the extent 
rectangle containing the object. 
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)utput 


$ RUN WALK 


DISPLAY LIST 

ELEMENTS 

IDENTIFIER 

0B3ECT TYPE 

113992 

UIS$C_0B3ECT_SEGMENT 

115328 

UIS$C_0B3ECT_ELLIPSE 

115575 

UIS$C_0B3ECT_PL0T 

115822 

UIS$C_0B3ECT_PL0T 

116069 

UIS$C_0B3ECT_PL0T 

116316 

UIS$C_0B3ECT_TEXT 

116810 

UIS$C_0B3ECT_TEXT 

117057 

UIS$C_0B3ECT_LINE 

FORTRAN PAUSE 


« 1 




The footsteps of fortune are slippery 
Mirth without measure is madness 
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UIS$GET^PARENT_SEGMENT 


Returns the parent segment identifier of the specified object. 


Format 

parenf_/cf=UIS$GET_PARENT_SEGMENT | } 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the parent segment identifier in the variable 
parent—id or RO (VAX MACRO). The parent segment identifier uniquely 
identifies a parent segment and is used as an argument in other routines. 

UIS$GET_PARENT_SEGMENT signals all errors; no condition values are 
returned. 


Arguments 


obi—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Object identifier. The obj_id argument is the address of a longword that 
uniquely identifies the object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg_id argument is the address of a longword that 
uniquely identifies the segment. See UIS$BEGIN—SEGMENT for more 
information about the seg_id argument. 
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Description 

If the specified object is the outermost segment or root segment, its own 
object identifier is returned. 
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UIS$GET_POINTER_POSITION 

Returns the current pointer position in world coordinates. 

Format 

sfafus=UIS$GEUOINTER_POSmON vd-id, wdUd, retx, 

rety 

Returns 

VMS Usage: boolean 
type: longword 

access: write only 

mechanism: by value 

Boolean value returned as the current position of the pointer in a status 
variable. UIS$GET_POINTER-POSITION returns the boolean TRUE value 
I if the pointer is within the visible portion of the viewport, 0 is returned if 
the pointer is outside the visible portion of the viewport. In the latter case, 
the X and y values are returned as 0,0. 

UIS$GET_POINTER_POSITION signals all errors; no condition values are 
returned. 


Arguments 

vdL/d 

VMS Usage: Identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

w(LJd 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 
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Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 


retx, rety 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


World coordinate pair. The retx and rety arguments are the addresses of 
f—floating point longwords that receives the pointer x and y world 
coordinates. 


Description 

Note that the returned status value should always be tested when using 
this routine, since it is always possible that the pointer could be outside the 
window when the service is called and the x,y values would be meaningless. 
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UIS$GET_POSITION 


Returns the current baseline position for text output. 


Format 

UlSSGET-POSITIdN vd-id, retx, rety 


Returns 

UIS$GET_POSITION signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd—id argument. 


retx, rety 

VMS Usage: fioating—point 
type: f—floating 

access: write only 

mechanism: by reference 

World coordinate pair. The retx and rety arguments are addresses of 
f—floating point longwords that receive the x and y world coordinate 
positions. 


Description 

U1S$TEXT and U1S$NEW—TEXT—LINE recognize the concept of current 
position. The position refers to the alignment point on the baseline of the 
next character to be output. 
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2K-5413-86 
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UIS$GET_PREVIOUS^OBJECT 


Returns the identifier of the previous object in the display list. 


Format 

prev_W=UIS$GET_PREVIOUS_OBJECT | ] [, flags] 

\ f J 


Returns 


VMS Usage; 
type; 
access; 
mechanism; 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the previous object identifier in the variable 
prev—id or RO (VAX MACRO). The previous object identifier uniquely 
identifies the previous object in the display list and is used as an argument in 
other routines. 


UIS$GET_PREV10US_0BJECT signals all errors; no condition values are 
returned. 


Arguments 


obj—id 
VMS Usage; 
type; 
access; 
mechanism; 


identifier 

longword (unsigned) 
read only 
by reference 


Object identifier. The obj_id argument is the address of a longword that 
uniquely identifies an object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg—id argument is the address of a longword 
that uniquely identifies a segment. See UIS$BEGIN—SEGMENT for more 
information about the seg—id argument. 
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flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Flags. The flags argument is the address of a longword that controls how the 
display list is searched. If the flags argument is specified using UIS$M_DL_ 
SAME—SEGMENT, the previous object in the segment containing the object 
specified is returned. 

If the flags argument is omitted, the previous object in the display list, 
regardless of the segment in which it is contained, is returned. 


Description 

If no previous object is found, a zero is returned. 


Illustration 

The following figure illustrates how UIS$GET_PREVIOUS_OBJECT of each 
previous object within the same segment. 


Root Segment 


Level 0 


Plot 


Ellipse 


Text 


Segment 


Text 


Level 1 


Segment 

prev—id 


Image 

' w' 

prev—ia 


New Text Line 
prev—id 


Text 

+ ' 

prev—id 


Ellipse 

t 

current—id 


ZK-5363-86 


The following figure illustrates how UIS$GET_PREVIOUS_OBJECT returns 
the object identifier of all objects in the display list. 
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Root Segment 


Level 0 

Plot 

Ellipse 

Text 

Segment 

Text 


1 _ 

_ f _ 

_ f _ 

_ f 

—. ♦ 


prev—id 

prev—id 

prev—id 

prev—id 

prev-id 


Level 1 

Image 

Plot 

New Text Line 

Text 

Ellipse 


t 

— t 

— t ^ 

— 1 — 

— t 


prevUd 

prev—id 

prevUd 

prev—id 

current—id 

ZK 5364 86 
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UIS$GET_ROOT_SEGMENT 


Returns the root segment of the specified virtual display. 


Format 

roof_/of=UIS$GET_ROOT^SEGMENT vd-id 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
write only 
by value 


Longword value returned as the root segment identifier in the variable 
root—id or RO (VAX MACRO). The root segment identifier uniquely identifies 
the root segment. 

UIS$GET_JROOT_SEGMENT signals all errors; no condition values are 
returned. 


Argument 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 


Description 

UIS$GET_ROOT_SEGMENT can be used with UIS$EXTRACT_OBJECT to 
extract an entire display list. 
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Screen Output 

$ run get_rootseg 

The root segment identifier for virtual display is 112968 
FORTRAN PAUSE 

Li 



Root Segment 



root-id 




Ellipse Plot Ellipse 


ZK-5366-86 
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UIS$GET--TBJNFO 

Returns the characteristics of the tablet device. 


Format 

sfaft/s=UIS$GET-_TB_INFO devnam, retwidth, retheight, 

retresoix, retresoly [,retpwidth, 
retpheight] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Longword value returned in a status variable. If the value 1 is returned, the 
pointing device is a tablet. If the value 0 is returned, the pointing device is 
a mouse and the returned information will be zeros. A tablet is required for 
digitizing. 

UIS$GET_TB_INFO signals all errors; no condition values are returned. 


Arguments 


devnam 

VMS Usage: 
type: 
access: 
mechanism: 


device_name 
character string 
read only 
by descriptor 


Device name. The devname argument is the address of a character string 
descriptor of the workstation device name. Specify the logical name 
SYS$WORKSTATION. 


retwidth 
VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Tablet width. The retwidth argument is the address of an f—floating point 
longword that receives the width of the tablet in centimeters. 
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retheight 

VMS Usage; 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Tablet height. The retheight argument is the address of an f—floating point 
longword that receives the height of the tablet in centimeters. 


retresoix 

VMS Usage: 
type: 
access; 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Tablet x resolution. The retresoix argument is the address of an f—floating 
longword that receives the x resolution of the tablet in centimeters per pixel. 


retresoly 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Tablet y resolution. The retresoly argument is the address of an f—floating 
point longword that receives the y resolution of the tablet in centimeters per 
pixel. 


retpwidth 
VMS Usage: 
type: 
access; 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Tablet width. The retpwidth argument is the address of a longword that 
receives the width of the tablet in pixels. 


retpheight 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Tablet height. The retpheight argument is the address of a longword that 
receives the height of the tablet in pixels. 
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Description 

A call to UIS$GET_TB_INFO is recommended prior to establishing 
digitizing. UIS$GET_TB_INFO returns a value indicating whether the 
device is a mouse or tablet. A tablet is required for digitizing. 

Note that you may invalidate the results of this call, if you unplug the tablet 
and replace it with a mouse while running an application. 
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UIS$GET_TB-POSITION 

Polls for the position of the pointing device on the tablet. 

Format 

UIS$GET--TB^POSITION tb-id ,retx ,rety 

Returns 

UlS$GET_TB_POSITION signals all errors; no condition values are returned. 

Arguments 

tb-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read oniy 

mechanism: by reference 

Tablet identifier. The tb_id argument is the address of a longword that 
uniquely identifies the tablet. See UIS$CREATE_TB for more information 
about the tb__id argument. 

retxjety 

VMS Usage: fioating_point 
type: f_fioating 

access: write oniy 

mechanism: by reference 

Digitizer position. The retx, rety arguments are the addresses of f_floating 
numbers that define the current digitizer position. 

Description 

The digitizer's position will not be available if the pointing device is a mouse. 

If the pointer is not on the tablet, UIS$GET_TB_POSITION returns the last 
pointer that was reported. 








UlS Routine Descriptions 18-173 

UIS$GET_TEXT_FORMATTING 


UIS$GET^TEXT_FORMATTING 


Returns a mask describing the enabled text formatting modes. 


Format 

formatting=U\S$GET^TEXT^FORMAJT\HG vd-id, atb 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
write only 
by value 


Longword mask returned as the current formatting mode in the variable 
formatting or RO (VAX MACRO). The following table lists the formatting 
modes. 


Formatting Mode 


Function 


UIS$C_TEXT_FORMAT_LEFT 

UIS$C_TEXT_FORMAT_RIGHT 

UIS$C_TEXT_FORMAT_CENTER 

UIS$C_TEXT_FORMAT_JUSTIFY 

UIS$C_TEXT_FORMAT_NOJUSTIFY 


Left justified, ragged right (default) 

Right justified, left ragged 

Centered line between left and right 
margin 

Justified lines, space filled to right margin 
No text justification 


UIS$GET_TEXT—FORMATTING signals all errors; no condition values are 
returned. 


Arguments 


vdL/d 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 
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atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block containing the text formatting attribute setting to 
be returned. 
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UIS$GET-TEXT_MARGINS 


UIS$GET_TEXT_MARGINS 


Returns the text margins for a line of text. 


Format 

UIS$GET_TEXT_MARGINS vd-id ,atb ,x ,y [,margin-length] 


Returns 

UIS$GET_TEXT_MARGINS signals all errors; no condition values are 
returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd—id argument is the address of a Iongword 
that uniquely identifies the virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Attribute block number. The atb argument is the address of a Iongword that 
identifies an attribute block containing the modified text margins attribute. 


x,y 

VMS Usage: 
type: 
access: 
mechanism: 


floating—point 
f—floating 
write oniy 
by reference 


Starting margin position. The x,y arguments are the addresses of £_floating 
longwords that receive the starting margin relative to the direction of text 
drawing. 
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margin—length 
VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Ending margin position. The margin—length is the address of an f—floating 
longword that receives the distance to the end margin. The margin is 
measured along the actual path of text drawing in the direction of the major 
text path. 


Screen Output 

$ run get_margins 

margin settings 

left margin x coordinate 5.00 

left margin y coordinate 15.00 

distance from left margin to right margin 20.00 

FORTRAN PAUSE 

Lj 




Hoist your sail when the wind is fair 

Hoist your sail when the wind is fair 

Hoist your sail when the wind is fair 

Hoist your sail when the wind is fair 

Hoist your sail when the wind is fair 
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UIS$GET_TEXT_PATH 


UIS$GET_TEXT^PATH 

Returns text path types. See UIS$SET_TEXT_JPATH for information about 
valid text path types. 


Format 

UIS$GET_TEXT_PATH vd—id, atb [,major][,minor] 


Returns 

UIS$GET_TEXT_PATH signals all errors; no condition values are returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a number that 
identifies an attribute block containing the text path attribute setting to be 
returned. 


major 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Major text path type. The major argument is the address of a code that 
identifies a major text path type. The major text path of text drawing is the 
direction of text drawing along a line. 
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minor 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Minor text path type. The minor argument is the address of a code that 
identifies a minor text path type. The minor path of text drawing is the 
direction used for new text line creation. 

Description 

The following table contains symbols for valid character drawing directions. 
Path Direction 

UIS$C_TEXT_PATH_RIGHT Left to right (default major text path) 
UIS$C_TEXT_PATH_LEFT Right to left 

UIS$C_TEXT_pAtH_UP Bottom to top 

UIS$C_TEXT_PATH_DOWN Top to bottom (default minor text path) 
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UIS$GET_TEXT^SLOPE 

Returns the angle of the actual path of text drawing relative to the major 
path in degrees. 


Format 

aA75r/e=UIS$GET_TEXT_SLOPE vd-id, atb 


Returns 


VMS Usage; 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by value 


Longword value returned as the angle of the actual path of text drawing 
relative to the major path in degrees in the variable angle or RO (VAX 
MACRO). Degrees are measured counterclockwise. 

UIS$GET—TEXT—SLOPE signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type; 
access; 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block from which the text slope attribute setting is to 
be returned. 
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Screen Output 


$ run get_slope 


The 

angle 

of 

the 

text 

baseline 

is 

0.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

34.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

68.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

102.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

136.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

170.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

204.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

238.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

272.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

306.00 

degrees 

The 

angle 

of 

the 

text 

baseline 

is 

340.00 

degrees 


FORTRAN PAUSE 
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UiS$GET-VCM-ID 


UIS$GET_VCM_ID 


Returns the virtual color map identifier used by the specified virtual display. 


Format 

i^c/7?_/flf=UIS$GET_VCM_ID vd-id 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
write oniy 
by vaiue 


Longword value returned as the virtual color map identifier in the 
variable vcm—id or RO (VAX MACRO). The virtual color map identifier 
uniquely identifies a virtual color map for a specified virtual display. See 
UIS$CREATE_COLOR_MAP for more information about the vcm_id 
argument. 

UIS$GET_VCM_ID signals all errors; no condition values are returned. 


Argument 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 
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UIS$GET_VIEWPORT_ICON 


UIS$GET_VIEWPORT_ICON 


Returns boolean value indicating whether or not the icon is visible. 


Format 

iboo/ear7=UIS$GET_VIEWPORT_ICON wd-id [Jcon^wd-id] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


boolean 

longword (unsigned) 
write only 
by value 


Boolean value returned in a status variable or RO (VAX MACRO) indicating 
whether an icon has replaced a viewport, a 1 denotes a TRUE condition; a 0 
denotes a FALSE condition. 


UIS$GET_VIEWPORT_ICON signals all errors; no condition values are 
returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_Jd argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


icon—wd—id 

VMS Usage: identifier 

type: longword (unsigned) 

access: write only 

mechanism: by reference 


Icon identifier. The icon—wd_id argument is the address of a longword that 
uniquely identifies the icon. 
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UIS$GET_VIEWPORT_ICON 


Screen Output 

$ run window_options 
Is the icon is visible? F = FALSE T 
T 


= TRUE 
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UIS$GET_VIEWPORT_POSITION 

UIS$GET_-VIEWPORT_POSITION 

Returns the position of the lower-left comer of the display viewport relative 
to the lower-left comer of the screen. 

Format 

UIS$GET_VIEWPORTPOSITION wd-id, retx, rety 
Returns 

UIS$GET_VIEWPORT_POSITION signals all errors; no condition values are 
returned. 


Arguments 

wd—id 

VMS Usage; identifier 
type: longword (unsigned) 

access; read only 
mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE 
for more information about the wd-id argument. 

retx,rety 

VMS Usage: floating-point 
type: f_floating 

access: write only 

mechanism: by reference 

Absolute device coordinate pair. The retx and rety arguments are the 
addresses of f_floating point longwords that receive the x and y coordinates 
of the display viewport origin in centimeters. 

These coordinates refer to the inside of the viewport and do not include the 
border. 
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UIS$GET_VIEWPORT_POSITION 


Description 

UIS$GET_VIEWPORT_POSITION is useful in the exact placement of 
windows. 


Screen Output 

See UIS$GET_VIEWPORT_SIZE. 
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UIS$GET_VIEWPORT_SIZE 


UIS$GET_VIEWPORT_SIZE 

Returns the size of the display viewport associated with the specified display 
window. 


Format 

UIS$GET_VIEWPORT_SIZE wd-id, retwidth, retheight 


Returns 

UIS$GET_VIEWPORT_SIZE signals all errors; no condition values are 
returned. 


Arguments 


wd-id 
VMS Usage; 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wdL_id argument. 


retwidth, retheight 
VMS Usage: fioating_point 
type: f_floating 

access: write oniy 

mechanism: by reference 


Display viewport width and height. The retwidth and retheight arguments 
are the addresses of f_jloating point longwords that receive the display 
viewport width and height in centimeters. 
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UIS$GET_VIEWPORT_SIZE 


Screen Output 


$ run set_viewpos_size 

The viewport position on the display screen in absolute coordinates 

X coordinate = 12.86 cm y coordinate = 1,97cm 

The physical dimensions of the display viewport 

width of viewport 9.97 cm height of viewport 9.97 cm 

FORTRAN PAUSE 

kj____ 
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UIS$GET-VISIBILITY 


UIS$GET_VISIBILITY 

Returns a boolean value that indicates whether or not the specified rectangle 
in the display window is visible. 

Format 

sfafus=UIS$GET_VISIBILITY vd-id, wd-id [,Xp [,X 2 , ysJ] 

Returns 

VMS Usage: boolean 
type: longword 

access: write only 

mechanism: by value 

Boolean value returned in a status variable or RO (VAX MACRO). The 
returned value, the visibility status, is a boolean TRUE only if the entire area 
is visible, and a boolean FALSE if even a portion of the area is occluded or 
clipped. 

UIS$GET_VISIBILITY signals all errors; no condition values are returned. 

Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See U1S$CREATE— 
WINDOW for more information about the wd_id argument. 
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UIS$GET_VISIBILITY 


Xi, Yi, X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read oniy 

mechanism: by reference 

World coordinates of a rectangle in the display window. The Xj and yj 
arguments are addresses of f_floating point numbers that define the lower- 
left comer of a rectangle in the display window. The Xi and y 2 arguments 
are addresses of f—floating point numbers that define the upper-right comer 
of a rectangle in the display window. 

If the coordinates of the rectangle are not specified, the dimensions of the 
entire display window are used by default. 

If only one point is specified, only that point is checked. 
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UIS$GET_WINDOW^TTRIBUTES 


UIS$GET-WINDOW-.ATTRIBUTES 

Returns the value of the mask WDPL$C_ATTRIBUTES used in the creation 
of the specified window. See UIS$CREATE_WINDOW for more information 
about window and viewport attributes. 


Format 

affr/it?ufes=UIS$GET_WINDOW_ATTRIBUTES wdUd 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword 
write only 
by value 


Longword mask representing one or more attributes of the specified display 
window and returned in the variable attributes or RO (VAX MACRO). See 
U1S$CREATE—WINDOW for more information. 


UlS$GET_WINDOW_ATTRIBUTES signals all errors; no condition values 
are returned. 


Argument 

wd—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE— 
WINDOW for more information about the wd—id argument. 
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UIS$GET_WINDOW-SIZE 


UIS$GET_WINDOW^SIZE 

Returns the dimensions of the display window. 

Format 

UIS$GET_WINDOW_SIZE vd-id, wd-id, Xp yp Xg, 

Returns 

UIS$GET_WINDOW_SIZE signals all errors; no condition values are 
returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about vd_Jd. 

ivdL/d 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE— 
WINDOW for more information about wd_id. 

xpypX2,y2 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

World coordinate pairs. The XpJi and the X2/y2 arguments are the addresses 
of f—floating longwords that receive the locations of the lower-left and 
upper-right comers of the display window in world coordinates. 
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UIS$GET-WRITING-INDEX 


UIS$GET_WRITING-INDEX 


Returns the writing color index for text and graphics output. 


Format 

/nGfex=UIS$GET_WRITING-.INDEX vd-id, atb 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by value 


Longword value returned as the color map index in the variable index or RO 
(VAX MACRO). 

UIS$GET_WRITING_INDEX signals all errors; no condition values are 
returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block from which the writing color index is 
obtained. 
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UIS$GET_WRITING-iNDEX 


Screen Output 

$ run get_writincjex 
The current writing index is 1 
FORTRAN PAUSE 
^ 
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UIS$GET_WRITING-MODE 


UIS$GET_WRITING_MODE 

Returns the writing mode. 


Format 

moc/e=UIS$GET_WRITING_MODE vd-id, atb 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by value 


Longword value returned as a UIS writing modes in the variable mode or RO 
(VAX MACRO). See Table 9-2 for more information about writing modes. 

UlS$GET_WRlTING_MODE signals all errors; no condition values are 
returned. 


Arguments 


yd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block from which the writing mode is 
obtained. 
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UIS$GET_WS_COLOR 


UIS$GET_WS_COLOR 

Returns the R (red), G (green), and B (blue) values associated with the 
workstation standard color. 


Format 

UIS$GET.-WS_COLOR vd—id, color—id, retr, retg, retb 

[,wd—id] 


Returns 

UIS$GET_WS_COLOR signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


color—id 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Workstation standard color. The color-id argument is the address of a 
longword integer that identifies a symbolic code for the workstation standard 
color. If the color—id argument is invalid, an error is signaled. 

The following table lists possible workstation standard color symbols and 
their current values. 
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UIS$GET_WS_COLOR 


Standard 

Color 

Symbol 

Background 

UIS$C_WS_BCOLOR 

Foreground 

UIS$C_WS_FCOLOR 

Black 

UIS$C_WS_BLACK 

White 

UIS$C_WS_WHITE 

Red 

UIS$C_WS_RED 

Green 

UIS$C_WS_GREEN 

Blue 

UIS$C_WS_BLUE 

Cyan 

U1S$C_WS_CYAN 

Yellow 

UlS$C_WS_YELLOW 

Magenta 

U1S$C_WS_MAGENTA 

Grey (25%) 

UIS$C_WS_GREY25 

Grey (50%) 

UIS$C_WS_GREY50 

Grey (75%) 

UIS$C_WS_GREY75 

retr 

VMS Usage: 

floating-point 

type: 

f—floating 

access: 

write only 

mechanism: 

by reference 

Red value. The retr argument is the address of an f_floating point longword 

that receives the red value. The red value is in the range of 0.0 to 1.0, 
inclusive. 

retg 

VMS Usage: 

floating-point 

type: 

f—floating 

access: 

write only 

mechanism: 

by reference 


Green value. The retg argument is the address of an f—floating point 
longword that receives the green value. The green value is in the range 
of 0.0 to 1.0, inclusive. 


retb 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f_floating 
write only 
by reference 
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UIS$GET_WS_COLOR 


Blue value. The retb argument is the address of an LJloating point longword 
that receives the blue value. The blue value is in the range of 0.0 to 1.0, 
inclusive. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. If this argument 
is specified, then it must be a valid wd_id associated with the virtual display, 
and the returned values are the realized colors for the specific device for 
which the window was created. 
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UIS$GET_WS_INTENSITY 


UIS$GET_WSJNTENSITY 

Returns the intensity values associated with a workstation standard color. 


Format 

UIS$GET_WS_INTENSITY vd-id, colored, reti [,wd-id] 


Returns 

UIS$GET_WS_1NTENS1TY signals all errors; no condition values are 
returned. 


Arguments 

vd-id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id ai^ument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 

color—id 

VMS Usage: longword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Workstation standard color identifier. The color_id argument is the address 
of a Iongword that identifies a symbolic code for the workstation standard 
color. If the color_id argument is invalid, an error is signaled. 

The following table lists possible workstation standard color symbols. 
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Standard 

Color 

Symbol 

Background 

U1S$C_WS_BCOLOR 

Foreground 

UIS$C_WS_FCOLOR 

Black 

UIS$C_WS_BLACK 

White 

UIS$C_WS_WHITE 

Red 

UIS$C_WS_RED 

Green 

UIS$C_WS_GREEN 

Blue 

UIS$C_WS_BLUE 

Cyan 

UIS$C_WS_CYAN 

Yellow 

UIS$C_WS_YELLOW 

Magenta 

UIS$C_WS_MAGENTA 

Grey (25%) 

UIS$C_WS_GREY25 

Grey (50%) 

UIS$C_WS_GREY50 

Grey (75%) 

UIS$C_WS_GREY75 


reti 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Intensity value. The reti argument is the address of an f_fIoating longword 
that receives the intensity value. The intensity value is in the range of 0.0 to 
1.0, inclusive. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

If this argument is specified, then it must be a valid wd_id associated with 
the virtual display, and the returned values are the realized intensities for the 
specific device for which the window was created. 
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UIS$HLS_TO_RGB 


UIS$HLS_TO_RGB 

Converts color representation values of hue, lightness, and saturation (HLS) 
to red, green, and blue (RGB) values. 

Format 

UIS$HLS_TO JGB H, L, S, retr, retg, retb 


Returns 

UIS$HLS_TO_RGB signals all errors; no condition values are returned. 


Arguments 

H 

VMS Usage: floating-point 
type: f_floating 

access: read only 

mechanism: by reference 

Hue. The H argument is the address of an f_floating number that defines 
the hue of a color. 

L 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Lightness. The L argument is the address of an f_floating number that 
defines the lightness of a color. 

S 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Saturation. The S argument is the address of an f_floating number that 
defines color saturation. 





UlS Routine Descriptions I 8-201 
UIS$HLS-TO-RGB 


VMS Usage: floating_point 
type: f_floating 

access: write only 

mechanism: by reference 

Red value. The retr argument is the address of an f_floating point longword 
that receives the red value. 

retg 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Green value. The retg argument is the address of an f_floating point 
longword that receives the green value. 

retb 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Blue value. The retb argument is the address of an f—floating point longword 
that receives the blue value. 
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UIS$HSV-TO-RGB 


UIS$HSV_TO_RGB 

Converts color representation values of hue, saturation, and value (HSV) to 
red, green, and blue (RGB) values. 

Format 

UIS$HSV_TO_RGB H, S, K retr, retg,retb 

Returns 

UIS$HSV_TO_RGB signals all errors; no condition values are returned. 


Arguments 

H 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Hue. The H argument is the address of an f_floating number that defines 
the hue of a color. 

S 

VMS Usage: floating-point 
type: f—floating 

access: read oniy 

mechanism: by reference 

Saturation. The S argument is the address of an f—floating number that 
defines the saturation of a color. 

V 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Value. The V argument is the address of an f_floating number that defines 
the value of a color. 
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VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Red value. The retr argument is the address of an f—floating longword that 
receives the red color value. 

retg 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Green value. The retg argument is the address of an f—floating longword 
that receives the green color value. 

retb 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Blue value. The retb argument is the address of an f—floating longword that 
receives the blue color value. 
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UIS$IMAGE 

Draws a raster image in a specified rectangle in the display viewport. 

Format 

UIS$IMAGE vd—id, atb, Xp yp x^, rasterwidth, 
rasterheight, bitsperpixel, rasteraddr 

Returns 

UIS$IMAGE signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

atb 

VMS Usage: iongword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block that modifies the image. 

Xi, Xi, X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the rectangle in the virtual display. The Xj and y^ 
arguments are the addresses of f—floating point numbers that define the 
lower-left comer of the rectangle in the virtual display. The X 2 and y 2 







UlS Routine Descriptions 18-205 
UIS$IMAGE 


arguments are the addresses of f__floating point numbers that define the 
upper-right comer of the rectangle in the virtual display. 

rasterwidth 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Width of the raster image. The rasterwidth argument is the address of a 
longword that defines the width of the raster image in pixels. 

rasterheight 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Height of the raster image. The rasterheight is the address of a longword 
that defines the height of the raster image in pixels. 

bitsperpixel 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of bits per pixel in the raster image. The bitsperpixel argument is 
the address of a longword that defines the number of bits per pixel in the 
raster image. The bitsperpixel argument is currently required to be 1 or 8. 

If the value 8 is specified for bitsperpixel on a single plane system, the 
results are unpredictable. 

rasteraddr 

VMS Usage: vector—longword—unsigned 
type: longword—unsigned 

access: read only 

mechanism; by reference 

Bitmap image. The rasteraddr argument is the address of an array that 
defines a bitmap image. You must first create a bitmap by defining a data 
structure such as a record or array. When you assign values to the field or 
array element in the data structure, you are setting the bits of the image to 
be drawn by UIS$IMAGE. See the Description section for information about 
setting bits. 
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Description 

The bitmap image is drawn to the display viewport as a raster image. The 
raster image dimensions are described by the width, height, and bits per 
pixel parameters. The width and height give the number of pixels in each 
dimension, and bits per pixel represents the number of bits that makes up 
each pixel. The raster is read from memory as "height" bit vectors each of 
which is "width" pixels long and each pixel is "bits/pixel" bits long. 

If the destination rectangle is larger than the raster size by at least an 
integer multiple, the raster is automatically scaled on a per pixel basis to the 
space available. Thus, a 1 x 1 raster can be written into an arbitrarily large 
destination rectangle, and the entire region is filled with the pattern. 

If the destination rectangle is not an exact multiple of the raster size, then 
the remaining space on the right and top will not be written. 

The procedure for mapping values in the bitmap to the raster image is as 
follows: 

1. Each bit in the raster is set from left-most bit to the right-most bit 

2. Each row is filled from the top row to the bottom row. 

NOTE: The raster image is not byte- or word-aligned. 

The following figure illustrates the setting of bits in the bitmap. 
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Example 


INTEGER*2 BITMAP(20) 

DATA BITMAP/2+0, 2 * 16380.5*12,2*1020.7*12.2*0/ 

VD_ID=UIS$CREATE_DISPLAY(0.0,0.0.40.0,40.0,10.0.10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’) 

CALL UIS$IMAGE(VD_ID,0.0.0,0.0,20.0,20.0,16,20,1,BITMAP) 
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Screen Output 
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UIS$INSERT_OBJECT 

Inserts the specified object into the display list at the position specified by the 
insertion pointer. See UIS$SET_INSERTION—POSITION for information 
about setting the pointer in the display list. 


Format 

UIS$INSERT_OBJECT | oty-W | 

I seg-id ) 


Returns 

UIS$INSERT—OBJECT signals all errors; no condition values are returned. 


Arguments 


obj—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Object identifier. The obj—id argument is the address of a longword that 
uniquely identifies an object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg—id argument is the address of a longword 
that uniquely identifies a segment. See UIS$BEGIN—SEGMENT for more 
information about the seg—id argument. 






18-210 UlS Routine Descriptions 
UIS$LINE 


UIS$LINE 

Draws an unfilled point, line, or series of unconnected lines depending on 
the number of positions specified. 


Format 

UIS$LINE vd-id, atb, Xp [,X2,y2 [,>-Xmyn]] 


Returns 

UIS$LINE signals all errors; no condition values are returned. 


Arguments 


vd-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block that modifies line style and line 
width or both. 


x,y 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


World coordinate pair. The x and y arguments are the addresses of f—floating 
point numbers that define a point in the virtual display. If the arguments 
are repeated to specify a second position, a line is created. Up to 126 world 
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coordinate pairs may be specified as arguments. See the "DESCRIPTION" 
section below for more information about this argument. 


Description 

If one position is specified, then a point is drawn. If two positions are 
specified, a single vector is drawn. If more than two positions are specified, 
unconnected lines are drawn. Up to 252 arguments can be specified, a 
maximum of a 126 unconnected lines are drawn using this routine. If a 
larger number of points must be specified in a single call, UIS$LINE—ARRAY 
should be used. 

The points or lines are drawn with the line pattern and width for the attribute 
block. UIS$LINE ignores the fill pattern attribute. 


Example 


call uis$line(vd_id.0.3.0.5.0,5.0,15.0,5.0.5.0.7.0.15.0.7.0,5.0, 
2 9.0,15.0, 

2 9.0,5.0.11.0.15.0.11.0.5.0.13.0,15.0. 

2 13.0.5.0.15.0.15.0,15.0,5.0.17.0.15.0) 


A single call to UIS$LINE draws five unconnected lines. 
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Screen Output 
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UIS$LINE-JVRRAY 

Draws an unfilled point, line, or series of unconnected lines depending on 
the number of positions specified. This routine performs the same functions 
as UIS$LINE except that x and y coordinates are stored in arrays. 


Format 

UIS$LiNE_ARRAY vd—id, atb, count, X—vector, y^vector 


Returns 

UIS$LINE—ARRAY signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd__id argument. 


atb 


VMS Usage; 
type: 
access: 
mechanism: 


iongword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block that modifies line style or line width 
or both. 


count 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 
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Number of points. The count argument is the address of longword integer 
that denotes the number of world coordinate pairs defined in the arguments 
x_vector and y_vector. 


x—vector, y—vector 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—signed 
f—floating 
read only 
by reference 


Array of x and y world coordinates. The x_vector argument is the address 
of an array of f—floating numbers whose elements are the x world coordinate 
values of points defined in the virtual display. The y—vector argument is the 
address of an array of f—floating numbers whose elements are the y world 
coordinate values of points defined in the virtual display. 


Description 

A maximum of 32,767 points can be plotted in a single call. U1S$LINE— 
ARRAY is the same as UIS$L1NE except that the x and y coordinates are 
specified using two arrays, each of length count points. 
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UIS$MEASURE_TEXT 


Measures a text string as if it were output in a virtual display. 


Format 

UIS$MEASURE_TEXT vd—id, atb, text—string, retwidth, 

retheight, [,ctllist, ctllen] [,posarray] 


Returns 

UIS$MEASURE_TEXT signals all errors; no condition values are returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a Iongword 
integer that identifies an attribute block that modifies text output. 


text—String 

VMS Usage: 
type: 
access: 
mechanism: 


char—string 
character string 
read only 
by descriptor 


Text string. The text—string argument is the address of a character string 
descriptor of a text string. 
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retwidth, retheight 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


World coordinate width. The retwidth and retheight arguments are the 
addresses of f—floating point longwords that receive the world coordinate 
width and height of the text. 


ctllist 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—unsigned 
longword (unsigned) 
read only 
by reference 


Text formatting control list. The ctllist argument is the address of an array 
of longwords that describe the font, text rendition, format, and positioning of 
fragments of the text string. See UIS$TEXT for a description of the control 
list and its commands. 


The control list consists of a sequence of data elements, each two longwords 
in length. The first longword of each element is a tag. The second longword 
is either a value particular to the type of element specified or zero. Following 
is a diagram showing the structure of a text control list. 
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UIS$C_TEXT_ATB 


Attribute Block Number 


UIS$C_TEXT_SAVEPOSITION 


0 


UIS$C_TEXT_IGNORE 


Command Value 


U IS$C_TEXT_EN D_OF_LIST 
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The following table describes valid formatting commands. 


Formatting Command 

Function 

Commands Without Values^ 

UIS$C_TEXT_NOP 

UIS$C_TEXT_RESTORE -POSITION 

UIS$C_TEXT_S AVE -POSITION 

Nil operation 

Restores the current writing position 

Saves the current writing position 

Commands Requiring Values 

UIS$C-TEXT-ATB 

UIS$C-TEXT-HPOS-ABSOLUTE 

UIS$C-TEXT_HPOS-RELATIVE 

UIS$C-TEXT-IGNORE 

Specifies an attribute block number 
Specifies a new current x position 

Modifies the current x position by a delta 
Skips n characters 


^Second longword must be zero. 
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Formatting Command 

Function 

Commands Requiring Values 



UIS$C_TEXT_NEW_LINE 

UIS$C_TEXT_TAB_ABSOLUTE 

UIS$C_TEXT_TAB_RELATIVE 

UIS$C_TEXT_VPOS_ABSOLUTE 

UIS$C_TEXT_VPOS_RELATIVE 

UIS$C_TEXT_WRITE 


Skips n new lines and positions at the left 
margin 

Writes white space to the new absolute 
position 

Writes white space to the new relative 
position 

Writes a new current y position 
Modifies the current y position by a delta 
Writes n characters 


Commands Not Requiring a Second Longword 

UlS$C_TEXT_END_OF_LIST Terminates the control list 


When UIS encounters illegal commands and values within the control list, it 
skips the invalid item and signals an error. 


cWen 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Length of the text formatting control list. The ctllen argument is the address 
of a longword that specifies the length of the text formatting control list in 
longwords. 

posarray 

VMS Usage: vector—longword—signed 

type: f—floating 

access: write only 

mechanism: by reference 


Character position array. The posarray argument is the address of an array 
of longwords that receives the character positions in world coordinates, 
that is, relative offsets at which each character would have been displayed. 
Following is a diagram showing the format of the character position array. 
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Character Cell 1 


Character Cell 2 


Character Cell n 


The width and height of the text string is calculated according to the 
formatting described in the atb and ctllist arguments. 


Relative Position x„ 


Relative Position y„ 
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Relative Position xi 


Relative Position yi 


Relative Position X 2 


Relative Position y 2 


Description 

UIS$MEASURE_TEXT is used in justification and text positioning 
applications. The routine returns the height and width of the text string 
in world coordinates. 
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UIS$MOVE^REA 

Shifts a portion of a virtual display to another position in the display 
window. 

Format 

UIS$MOVE_AREA vd—id, Xp yp x^, new—x, new^y 

Returns 

UIS$MOVE_AREA signals all errors; no condition values are returned. 

Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

xpyuX2,y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the source rectangle. The Xj and y^ arguments are the 
addresses of f—floating point numbers that define the lower-left comer of 
the source rectangle. The X 2 and yi are the addresses of f—floating point 
numbers that define the upper-right corner of the source rectangle. 

new—x, new—y 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinate pair. The new—x and new—y arguments are the 
addresses of f—floating point numbers that define the lower-left corner of 
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the destination rectangle. The proportions of the coordinate space of the 
destination rectangle are the same as those of the source rectangle. 


Description 

Note that display objects that are only partially contained within the specified 
source rectangle, though partially moved within existing display windows 
will be completely moved within the display list. 

The nonoccluding portion of the source rectangle (if any) is erased after the 
operation. 

NOTE; To avoid distortion within the destination rectangle, the aspect 
ratios of the source rectangle and the display viewport must be equal. 
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UIS$MOVE_VIEWPORT 

Moves the display viewport on the workstation screen. 


Format 

UIS$MOVE_VIEWPORT wd-id, attributes 


Returns 

UIS$MOVE—VIEWPORT signals all errors; no condition values are returned. 


Arguments 

wd-Jd 

VMS Usage: identifier 
type; iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE— 
WINDOW for more information about the wd—id argument. 

attributes 

VMS Usage: item_list—pair 
type; Iongword 

access: read only 

mechanism: by reference 

Display viewport attribute list. The attributes argument is the address of 
data structure that contains Iongword pairs, or doublets. The first Iongword 
stores an attribute ID code and the second Iongword holds the attribute value 
(which can be real or integer). 

The following figure describes the structure of the window attributes list. 
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Attribute ID code 
(WDPL$C_xxx) 

Longword value for attribute 
identified in previous longword 

2nd attribute ID code 



End of list ^ 0 

(WDPL$C_END_OF_LIST) 
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Only positional attributes are significant. 
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UIS$MOVE^WINDOW 


Redefines the world coordinates of the specified display window. 


Format 

UIS$MOVE_WINDOW vd-id, wd-id, Xp x^, 


Returns 

UIS$MOVE—WINDOW signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_Jd argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE— 
WINDOW for more information about the wd_id argument. 


Xi, Yi, X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the new display window. The Xj and arguments 
are the addresses of f—floating point numbers that define that lower-left 
comer of the display window. The X 2 and y 2 arguments are the addresses 
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of f_floating point numbers that define the upper-right comer of the new 
display window. 


Description 

UIS$MOVE—WINDOW redefines the world coordinates of the specified 
display window. As a result, what is displayed in the associated display 
viewport may change. You can pan around a virtual display or scroll through 
a virtual display. If the display window rectangle changes dimensions or 
aspect ratio, then scaling is performed to map the new window size to the 
existing display viewport size. 
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UIS$NEW_TEXT^LINE 

Moves the current text position along the actual path of text drawing to the 
starting margin, and then in the direction of the minor text path. Depending 
on the minor text path, the width or height of the character cell is used for 
spacing between characters and lines. 


Format 

UIS$NEW_TEXT_LINE vdUd, atb 


Returns 

UIS$NEW_TEXT_LINE signals all errors; no condition values are returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
Iongword 
read only 
by reference 


Attribute block number. The atb argument is the address of a Iongword 
integer that identifies an attribute block that modifies text output. 


Description 

Font, text path, character spacing, and text slope attributes influence the 
behavior. 
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UIS$PLOT 

Draws a filled or unfilled point, line, or polygon depending on the number of 
positions specified. 


Format 

UIS$PLOT vd-Jd, atb, x,, y, [,...x„,yn]] 


Returns 

UIS$PLOT signals all errors; no condition values are returned. 


Arguments 


vd-jd 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block that modifies line style and line 
width or both. 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


World coordinate pair. The x and y arguments are the addresses of f—floating 
point numbers that define a point in the virtual display. If the arguments 
are repeated to specify a second position, a line is created. Up to 126 world 
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coordinate pairs may be specified as arguments. See the Description section 
below for more information about this argument. 


Description 

If one position is specified, then a point is drawn. If two positions are 
specified, a single vector is drawn. If more than two positions are specified, 
a connected polygon is drawn. Up to 252 arguments can be specified, giving 
a maximum of a 126-point polygon using this routine. If a larger number of 
points must be specified in a single call, UIS$PLOT_ARRAY should be used. 

The points or lines are drawn with the line pattern and width for the attribute 
block, and if the fill pattern attribute is enabled for the attribute block, the 
enclosed area is filled with the current fill pattern. 

NOTE: VAX PASCAL application programs should use UIS$PLOT_ARRAY 
to create lines and polygons. 


Example 


REAL*4 I 

VD_ID=UIS$CREATE_DISPLAY(0.0.-1.1,360.0,1.1.10.0,10.0) 
WD_ID=UIS$CREATE_WINDOW(VD_ID,’SYS$W0RKSTATI0N’.’SINE CURVE’) 
CALL UIS$PL0T(VD_ID.0.0.0.0.0,360.0,0.0) 

DO 1=1,360 

CALL UIS$PL0T(VD_ID.0.I.SIND(I)) 

ENDDO 


The preceding example draws a sine curve. 
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UIS$PLOT__ARRAY 

Draws an unfilled or filled point, line or polygon depending on the 
number of positions specified. This routine performs the same functions 
as UIS$PLOT. 


Format 

UIS$PLOT_ARRAY vd—id, atb, count, x^vector, y—vector 


Returns 

UIS$PLOT_ARRAY signals all errors; no condition values are returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block that modifies line style or line width 
or both. 


count 


VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
longword (unsigned) 
read only 
by reference 
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Number of points. The count argument is the address of longword integer 
that denotes the number of world coordinate pairs defined in the arguments 
x_vector and y_vector. 


X—vector, y—vector 


VMS Usage: 
type: 
access: 
mechanism: 


vector^longword—signed 
floating 
read only 
by reference 


Array of x and y world coordinates. The x—vector argument is the address 
of an array of f—floating numbers whose elements are the x world coordinate 
values of points defined in the virtual display. The y—vector argument is the 
address of an array of f—floating numbers whose elements are the y world 
coordinate values of points defined in the virtual display. 


Description 

A maximum of 65,535 points can be plotted in a single call. UIS$PLOT— 
ARRAY is the same as UIS$PLOT except that the x and y coordinates are 
specified using two arrays, each of length count points. 
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UIS$POR-VIEWPORT 

Pops the viewport associated with the display window to the forefront of the 
screen, over any other viewports that currently occlude it. 


Format 

UIS$POP_VIEWPORT wd-id 


Returns 

UIS$POP_VIEWPORT signals all errors; no condition values are returned. 


Argument 

wd^id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 
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UIS$PRESENT 


Verifies that UIS software is installed on the system. 


Format 

sfaft/s=UIS$PRESENT [major—version][,minor—version] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


Longword value returned in the variable status or RO (VAX MACRO). A 
value of 1 TRUE indicates that UIS is installed on the system. Otherwise, the 
error status SHR$_PROD_NOTINS is returned if UIS$PRESENT is executed 
on a VAX/VMS system running the stub UIS shareable image. The stub 
shareable image is currently installed on non-VAXstation systems. 


Arguments 

major—version 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Major version number. The major—version argument is the address of a 
word that receives the major version number. For UIS Version 3.0, the major 
version number 3 is returned. 


minor—version 


VMS Usage: 
type: 
access: 
mechanism: 


word—unsigned 
word (unsigned) 
write only 
by reference 


Minor version number. The minor—version argument is the address of a 
word that receives the minor version number. For UIS Version 3.0, the minor 
version number 0 is returned. 
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UIS$PRIVATE 

Associates application-specific data with the most recently output graphic 
information (graphics or text) or with the specified graphic object. 


Format 

UIS$PRIVATE I ] , facnum, buffer 

I vd—id ) 


Returns 

UIS$PRIVATE signals all errors; no condition values are returned. 


Arguments 


obj—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Object identifier. The obj_id argument is the address of a Iongword that 
uniquely identifies an object. 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


facnum 


VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Facility number. The facnum argument is the address of a Iongword that 
identifies the creator of the private data. 
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Values defined with the high bit set are reserved to DIGITAL. 


buffer 


VMS Usage: 
type: 
access: 
mechanism: 


vector—byte—unsigned 
byte (unsigned) 
read oniy 
by descriptor 


Location of the private data. The buffer argument is a descriptor of an array 
of bytes. The byte array contains the private data. 


Description 

If you select a graphic item and store it in a file, the application-specific data 
will be copied with it. If nothing has been output since the beginning of a 
segment, the data will be associated with the segment. 

Many private data items can be associated with the same graphic object. 
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UIS$PUSH_VIEWPORT 

Pushes the viewport associated with the display window to the background 
of the screen, behind any other viewports it occludes. 


Format 

UIS$PUSH_VIEWPORT wd-id 


Returns 

UIS$PUSH—VIEWPORT signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 







18>240 UlS Routine Descriptions 
UlSSPUSH-VIEWPORT 





















































UlS Routine Descriptions 18-241 

UIS$READ_CHAR 


UIS$READ_CHAR 


Allows an application to read a single character from the keyboard. 


Format 

/ceyit?uf-UIS$READ_CHAR kb-id [,flags] 


Returns 


VMS Usage; 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Longword integer returned key information in the variable keyhuf or RO 
(VAX MACRO). The keybuf variable is the address of a longword buffer 
that receives the key information. The low two bytes are the key code. 

The key codes are based on the codes found in the module $SMGDEF in 
SYS$L1BRARY:STARLET.MLB. Bit <31 > is set to 1 to indicate that the key 
is down. For additional information about keybuf, see the DESCRIPTION 
section. 


UIS$READ_CHAR signals all errors; no condition values are returned. 


Arguments 


kb-id 


VMS Usage; 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual keyboard identifier. The kb—id argument is the address of a 
longword that uniquely identifies a virtual keyboard. See U1S$CREATE_ 
KB for more information about the kb—id argument. 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Rags. The flags argument is the address of a longword mask that controls 
whether U1S$READ_CHAR executes immediately or until a character is 
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received. If bit <0> is clear, UIS$READ_CHAR waits until a character is 
typed. If bit <0> is set and no character is currently waiting, UIS$READ- 
CHAR returns a value of 0. 

Specify UIS$M_NOWAIT to set bit <0> in the longword mask. 


Description 

The following table defines the bits in the high- and lower-order word. 


Field 

Symbol 

1-16 

UIS$W_KEY_CODE 

28 

UIS$V_KEY_SHIFT^ 

29 

uis$v_key_ctrl1 

30 

UIS$V_KEY_LOCK^ 

31 

UIS$V_KEY_DOWN 


Whis symbol is returned as SET if the corresponding key on the keyboard was down when 
the input event occurred. 
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UIS$RESIZE^WINDOW 

Deletes the old display window and creates a new window. The routine 
reexecutes the display list of the virtual display, if it exists. 


Format 

UIS$RESIZE_WINDOW vd-id, wd-id [,new-abs-x, 

new—abs—y] [,new—width, 
new—height] [,new—wc—Xp 
new—wc—Yp new—wc—X2, 
new—wc—y2,] 


Returns 

UIS$RESIZE—WINDOW signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage; 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

Iongword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE— 
WINDOW for more information about the wd—id argument. 






18-244 UlS Routine Descriptions 
UIS$RESIZE-WINDOW 


new—abs—x, new—abs—y 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Absolute device coordinate pair. The new_ab8_x and new_abs_y 
arguments are the addresses of f_floating point numbers that define the 
location of the newly resized display viewport in centimeters. 

new—width, new—height 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Width and height of the newly resized display viewport. The width and 
height arguments are the addresses of f_floating point numbers that define 
the width and height of the newly resized display viewport in centimeters. 

new—wc—x^, new—wc—yi, new—wc—X2, new—wc—y2 

VMS Usage: floating-point 

type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the newly resized display window. The Xi and yj 
arguments are the addresses of f—floating point numbers that define the 
location of the lower-left comer of the resized display window in world 
coordinates. The X 2 and y 2 arguments are the addresses of f—floating point 
numbers that define the location of the upper-right comer of the resized 
display window in world coordinates. 


Description 

The viewport resize operation of the user interface uses 
UIS$RESIZE_WINDOW by default. 

If UIS$RESIZE—WINDOW is called outside an AST routine, the value of all 
unspecified parameters defaults to those specified in 
UlS$CREATE_WINDOW. 

If UIS$RESIZE—WINDOW is called within an AST routine, the value of all 
unspecified parameters defaults to the current values associated with the 
absolute position, dimensions, and world coordinate range of the stretchy 
box. 
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UIS$RESTORE_CMS_COLORS 

Resets the appropriate entries in the hardware color map to the current RGB 
values in the color map segment. 


Format 

UIS$RESTORE_CMS_COLORS cms-id 


Returns 

UIS$RESTORE_CMS_COLORS signals all errors; no condition values are 
returned. 


Argument 


cms—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 



Color map segment identifier. The cms—id argument is the address 
of a Iongword that uniquely identifies the color map segment. See 
UIS$CREATE—COLOR _MAP_SEG for more information about the 
cms—id argument. 


Description 

An application running in an unfavorable environment (where other appli¬ 
cations are sharing hardware color map entries) can use UIS$RESTORE— 
CMS—COLORS to reestablish all its entries when it is the active application. 
Normally, this call is not required since the UIS window management 
software transparently handles the multiplexing of the hardware color map. 
If possible, the update is synchronized to the display's vertical retrace. 
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UIS$RGB_TO_HLS 

Converts red, green, and blue (RGB) color representation values to hue, 
lightness, and saturation (HLS) color values. 

Format 

UIS$RGB_TO_HLS R, G, B, reth, retl, rets 

Returns 

UIS$RGB_TO_HLS signals all errors; no condition values are returned. 

Arguments 

R 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Red value. The R argument is the address of a longword that defines the red 
color value. 

G 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Green value. The G argument is the address of a longword that defines the 
green color value. 

B 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Blue value. The B argument is the address of a longword that defines the 
blue color value. 
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ref/i 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f_floating 
write only 
by reference 


Hue. The reth argument is the address of an LJloating point longword that 
receives the hue color value. 


ret! 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
write only 
by reference 


Lightness. The retl argument is the address of an f—floating point longword 
that receives the lightness value. 


rets 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f-floating 
write only 
by reference 


Saturation. The rets argument is the address of an f—floating point longword 
that receives the color saturation value. 
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UIS$RGB__TO^HSV 

Converts color representation values of red, green, and blue (RGB) to hue, 
saturation, and value (HSV), 

Format 

UIS$RGB_TO_HSV R, G, B, reth, rets, retv 

Returns 

UIS$RGB_TO_HSV signals all errors; no condition values are returned. 


Arguments 

R 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Red value. The R argument is the address of an f_floating number that 
defines the red color value. 

G 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Green value. The G argument is the address of an f_floating number that 
defines the green color value. 

B 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Blue value. The B argument is the address of an f—floating number that 
defines the blue color value. 
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reth 

VMS Usage: floating_point 
type: f_floating 

access: write only 

mechanism: by reference 

Hue. The reth argument is the address of an f_floating longword that 
receives the hue value. 

rets 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Saturation. The rets argument is the address of an f_floating longword that 
receives the saturation value. 

retv 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Value. The retv argument is the address of an f—floating longword that 
receives the value of the color. 
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UIS$SET__ADDOPT-_AST 

Specifies a user-requested AST routine to be executed whenever the 
"Additional Options" menu item is selected in the Window Options Menu. 

Format 

UIS$SET_ADDOPT_AST wd-id, [astadr [,astprm]] 

Returns 

UIS$SET_ADDOPT_AST signals all errors; no condition values are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

AST routine. The astadr argument is the address of a procedure entry 
mask of a user-supplied subroutine that is called at AST level whenever the 
"Additional Options" item in the Window Options Menu is selected. 

astprm 

VMS Usage: user_arg 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

AST parameter. The astprm argument is the address of a single argument 
or data structure such as an array or record to be used by the AST routine. 
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Calls to UIS$SET_ADDOPT_AST in VAX FORTRAN application programs 
should be coded as follows: %REF(%LOC(astprm)). 


Description 

Additional options are disabled by default. 
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UIS$SET_ALIGNED_POSITION 

Sets the current position for text output at the upper-left comer of the 
character cell of the next character. See UIS$GET_ALIGNED_POSITION for 
information about returning text alignment data. 


Format 

UIS$SET_ALIGNED_POSITION vd-id, atb, x, y 


Returns 

UIS$SET_ALIGNED_POSITION signals all errors; no condition values are 
returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Attribute block number. The atb is the address of a Iongword that identifies 
an attribute block. 


X, y 

VMS Usage: 
type: 
access: 
mechanism: 


floating-number 
f—floating 
read oniy 
by reference 


World coordinate pair. The x and y arguments are the addresses of f—floating 
point numbers that define the current position for text output. 






18-254 UlS Routine Descriptions 
UIS$SET_ALIGNED_POSITION 


Description 

UIS$SET_ALIGNED_POSITION is useful in applications that know the 
position of the upper left comer, but also do not know enough about the font 
baseline to determine the proper alignment point. The position is converted 
into the proper alignment point using the font specified in the given attribute 
block. 

UIS maintains the current text position as a baseline position. 

Screen Output 



One reason is as good\as fifty 



Text alignment 
along top of the 
character cell 


ZK 5384 86 
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UIS$SET_ARC_TYPE 

Sets the current arc type used in the UIS$ELLIPSE and UIS$CIRCLE 
routines. 


Format 

UIS$SET_ARC_TYPE vd—id, iatb, oatb, arc—type 


Returns 

UIS$SET_ARC_TYPE signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

iatb 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
Iongword integer that identifies an attribute block. 

oatb 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
Iongword that identifies a newly modified attribute block that controls the 
appearance of an arc. 
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arc—type 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Arc type code. The arc_type argument is the address of a longword value 
that redefines the attribute setting of the input attribute block. Specify one 
of the following constants UIS$C_ARC_PIE, UIS$C_CHORD, or UIS$C_ 
ARC-OPEN. 


The following table lists symbols for arc types and their functions. 


Symbol 

Function 

UIS$C_ARC_CHORD 

UIS$C_ARC_OPEN 

UIS$C_ARC_PIE 

Draws a line connecting the end points of the arc 

Does not draw any lines (default) 

Draws radii to the end points of the arc 
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Screen Output 
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UIS$SET.BACKGROUND_INDEX 

Sets the background color index for text and graphics output. 


Format 

UIS$SET_BACKGROUND_INDEX vd-id, iatb, oatb, index 


Returns 

UIS$SET_BACKGROUND_INDEX signals all errors; no condition values are 
returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

iatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
longword integer that specifies the attribute block to be modified. 

oatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

-mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
longword integer that identifies the newly modified attribute block. 
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index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Color map index. The index argument is the address of a longword that 
specifies the color map index. If the index exceeds the maximum index for 
the associated color map, an error is signaled. 
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UIS$SETJUTTON__AST 

Allows an application to find out when a button on the pointing device is 
depressed or released in a given rectangle within a display viewport. 

Format 

UIS$SET_BUTTON^ST vd-id, wd-id [,astadr [,astprm] 

,keybuf][, x„ y,, x^, y^; 

Returns 

UIS$SET_BUTTON_AST signals all errors; no condition values are returned. 


Arguments 

vdUd 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE_DISPLAY for 
more information about the vd_id argument. 

wd—id 

VMS Usage: identifier 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wdLid argument. 

astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

AST routine. The astadr argument is the address of an entry mask to a 
procedure that is called at AST level whenever a pointer button is depressed 
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or released. To cancel the AST-enabling request of UIS$SET_BUTTON_ 
AST, specify 0 in the astadr argument. 


astprm 
VMS Usage: 
type: 
access: 
mechanism: 


user_arg 

iongword (unsigned) 
read only 
by reference 


AST parameter. The astprm argument is the address of a single argument or 
data structure, such as a record or an array, to be passed to the AST routine. 
Calls to UIS$SET_BUTTON_AST in FORTRAN application programs should 
be coded as follows: %REF(%LOC(astprm)). 


keybuf 

VMS Usage: 
type: 
access: 
mechanism: 


address 

iongword (unsigned) 
write only 
by reference 


Key buffer. The keybuf argument is the address of a Iongword buffer 
that receives button information whenever a pointer button is depressed 
or released. The low two bytes are the key code. The buttons are 
located on the left, center, and right of the device and are defined as 
UIS$C_POINTER_BUTTON_l, UIS$C_POINTER_BUTTON_2, UIS$C_ 
POINTER_BUTTON_3, and UIS$C_POINTER-BUTTON_4 respectively. 

The bit <31 > is set to 1 if the button has been pressed, and 0 if the button 
has been released. The buffer is not overwritten with subsequent button 
transitions until the AST routine completes. 

The following table defines the bits in the high- and lower-order word. 


Field 

Symbol 

1-16 

UIS$W_KEY_CODE 

28 

UIS$V_KEY_SHIFT^ 

29 

uis$v_key_ctrl1 

30 

uis$v_key_lock1 

31 

uis$v_key_down’ 


^This symbol is returned as SET if the corresponding key on the keyboard was down when 
the input event occurred. 
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Xi, /i, X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of a rectangle in the display window. The Xj and y| 
arguments are the addresses of f_floating point numbers that define the 
lower-left comer of a rectangle in the display window. The X 2 and y 2 
arguments are the addresses of f_floating point numbers that define the 
upper-right comer of a rectangle in the display window. If no rectangle is 
specified, the entire display window is assumed. 


Description 

This function can be called any number of times for different rectangles 
within the same display window or many display windows. 

To disable UIS$SET_BUTTON_AST, omit the astadr, astprm, and keybuf 
arguments. 

Pointer Region Priorities 

UIS pointer regions are placed on the VAXstation screen in the order in 
which they are created. Therefore, if you create two overlapping viewports, 
and then use UIS$SET_POINTER_PATTERN, UIS$SET_BUTTON_AST, 
or UIS$SET_POINTER_AST to define different pointer patterns for each 
viewport, the correctness of the result will depend on the order in which 
you both created the viewports and defined the cursor regions. For example, 
if you create the viewports and define the cursor patterns in the following 
manner, the viewport 1 cursor pattern will have a higher priority than 
viewport 2 cursor pattern in the overlapping region. 

1. Create viewport 1 

2. Create overlapping viewport 2 

3. Define viewport 2 cursor pattern 

4. Define viewport 1 cursor pattern 
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The preceding example causes the unexpected result that the viewport 1 
cursor pattern will take priority over the viewport 2 cursor pattern in the 
overlapping region. This problem can be corrected by creating the viewports 
and defining the cursor patterns in the same order. To correct the problem, 
create the viewports and define cursor patterns in the following order: 

1. Create viewport 1 

2. Define viewport 1 cursor pattern 

3. Create overlapping viewport 2 

4. Define viewport 2 cursor pattern 

The solution is for either UlS or your application to always pop the viewport 
before defining the cursor region for it. 
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UIS$SET^CHAR^ROTATION 

Sets the angle of character rotation, measured counterclockwise relative to 
the actual path of text drawing. 


Format 

UIS$SET_CHAR_ROTATION vd-id ,iatb ,oatb,angle 


Returns 

UlS$SET_CHAR_ROTATION signals all errors; no condition values are 
returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


iatb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Input attribute block number. The iatb argument is the address of a number 
that identifies an attribute block to be modified. 


oath 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Output attribute block number. The oatb argument is the address of a 
modified attribute block. 
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angle 

VMS Usage: floatmg_point 
type: f_floating 

access: read only 

mechanism: by reference 

Angle of character rotation. The angle argument is the address of an 
f—iloating point number that defines the angle of character rotation in 
degrees counterclockwise about the baseline point relative to the actual path 
of text drawing. 


Description 

For example, an angle of 0 degrees (the default) means that the character's 
baseline vector and the actual path of text drawing form an angle of 0 
degrees. 


Exampie 


CALL UIS$SET_FONT(VD^ID.0.1.’MY_F0NT_5’) 
CALLUIS$SET_TEXT_MARGINS(VD_ID.1.1.1.0.20.0.18.0) 
CALL UIS$SET_ALIGNED_P0SITI0N(VD_ID.1.1.0.20.0) 

DO 1=0.360.40 

CALL UIS$TEXT(VD_ID.l.’Slow down—’) 

CALL UIS$SET_CHAR_R0TATI0N(VD_ID.1.2.FLOAT(I)) 
CALL UIS$TEXT(VD_ID.2.’Avoid skidding!’) 

CALL UIS$NEW_TEXT_LINE(VD_ID.2) 

ENDDO 
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UIS$SET_CHAR_SIZE 

Sets the world coordinate size of a specified character set. 

Format 

UIS$SET_CHAR_SIZE vd-id, iatb, oatb [,char] [,width] 

[.height] 

Returns 

UIS$SET_CHAR_SIZE signals all errors; no condition values are returned. 

Arguments 

vdJid 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

iatb 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
Iongword that identifies an attribute block to be modified. 

oatb 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
Iongword that identifies a modified attribute block. 
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char 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Single character. The char argument is the address of a descriptor of a single 
character. 


If char is not specified, the widest character in the font is chosen. 


width 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Character width. The width argument is the address of an f_floating point 
longword that defines the character width in world coordinates. 


See DESCRIPTION section for information about omitting the width 
argument. 


height 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Character height. The height argument is the address of an f—floating point 
longword that defines the character height in world coordinates. 

See DESCRIPTION section for information about omitting the height 
argument. 


Description 

To disable character scaling, omit all of the following arguments: char, 
width, and height. 

To scale characters to their nominal size as specified in the font, do not 
specify width and height. Scaling is only visible when you use a window 
that does not have the same aspect ratio as the virtual display. The particular 
character you specify in the argument char makes no difference in this case. 
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If you specify either width or height only, characters are scaled to the size 
you specify and in the direction you specify. In the unspecified direction, 
characters are scaled so as to maintain the same ratio of width and height as 
the unsealed characters. 
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Screen Output 
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UIS$SET_CHAR_SLANT 

Sets the character slant angle. 


Format 

UIS$SET_CHAR_SLANT vd-id, iatb, oatb, angle 


Returns 

UIS$SET_CHAR—SLANT signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

iatb 

VMS Usage: iongword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a number 
that identifies an attribute block to be modified. 

oatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
number that identifies a modified attribute block. 
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angle 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Angle of character slant. The angle argument is the address of an f_floating 
point number that defines the angle of character slant in degrees. 

The character slant angle refers to an angle formed by the character's up 
vector and baseline vector. 

For example, 0 degrees (the default) indicates that the character up vector 
is perpendicular to the baseline vector, and the character is not slanted. A 
counterclockwise movement from 0 degrees produces a negative angle of 
character slant. A clockwise movement from 0 degrees produces a positive 
angle of character slant. 


Screen Output 


Vnien victorious, shout RHINEHART! 
l/hen victorious, shout RHINEHART! 
k^en victorious, shout RHINEHART/ 


character slanting 


en victorious, s\\out 
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UIS$SET_CHAR_SPACING 

Sets the attribute that controls the amount of additional spacing between text 
characters {x factor) and between text lines {y factor) when the UIS$NEW_ 
LINE—TEXT routine is used. 


Format 

UIS$SET_CHAR_SPACING vd-id, iatb, oatb, dx, dy 


Returns 

UIS$SET—CHAR-SPACING signals all errors; no condition values are 
returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_Jd argument. 


iatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Input attribute block number. The iatb argument is the address of a 
Iongword value that identifies an attribute block to be modified. Either the 
attribute block 0 or a previously modified attribute block may be specified. 


oatb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 
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Output attribute block number. The oatb argument is the address of a 
longword value that identifies the newly modified attribute block that 
controls the spacing between characters. 


dx 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—fioating 
read only 
by reference 


Additional x factor spacing. The dx argument is the address of an f_floating 
point longword value that defines the x spacing factor. If this argument 
is 0.0, no additional spacing is performed. Negative values are allowed, 
characters may overlap. 


dy 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Additional y factor spacing. The dy is the argument of an f—floating point 
longword value that defines the y spacing factor. If this argument is 0.0, no 
additional spacing is performed. Negative values are allowed, characters may 
overlap. 


Description 

The values of the x and y factors are multiplied by the width or height of the 
character, and the resulting value is used as the additional spacing distance. 

Proportionally spaced characters maintain their appropriate spacing. 

The default is no extra spacing. 
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Screen Output 



ZK-5254 86 
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y spacing 


Nature does nothing in vain 
Nature does nothing in vain 

Nature does nothing in vain 
Nature does nothing in vain 

Nature does nothing in vain 

Nature does nothing in vain 


Nature does nothing in vain 
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ZK-5252 86 
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UIS$SET_CLIP 

Sets a clipping rectangle in the virtual display and enables clipping for this 
attribute block. 

Format 

UIS$SET_CLIP vd—id, iatb, oatb [,Xp yp x^, 

Returns 

UIS$SET_CLIP signals all errors; no condition values are returned. 


Arguments 

vdL/d 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

iatb 

VMS Usage: iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
Iongword value that identifies an attribute block to be modified. Either 
the attribute block 0 or a previously modified attribute block can be specified. 

oatb 

VMS Usage: longword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
Iongword value that identifies a newly modified attribute block. 
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Xu Yu X2, Yi 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the clipping rectangle. The Xj and yj arguments are 
the addresses of f_floating point numbers that define the lower left corner 
of the clipping rectangle in world coordinates. The and yi arguments are 
the addresses of f_floating point numbers that define the upper right comer 
of the clipping rectangle in world coordinates. Only graphic objects and 
portions of graphic objects drawn within the clipping rectangle are seen. 

If the world coordinates of the clipping rectangle comers are not specified, 
then clipping is disabled for this attribute block. 


Example 


WD_ID1=UIS$CREATE_WIND0W(VD_ID.’SYS$WORKSTATION’.’AFTER’) 
CALL UIS$ERASE(VD_ID) 

CALL UIS$SET_CLIP(VD_ID.0,1,5.0,5.0,15.0,15.0) 

CALL UIS$PL0T(VD_ID,1.2.0,2.0,18.0.2.0,18.0,18.0,2.0,18.0, 

2 2 . 0 , 2 . 0 ) 

CALL UIS$PL0T(VD_ID.1,2.0.2.0,18.0,18.0.) 

CALL UIS$PL0T(VD_ID,1,2.0,18.0,18.0,2.0) 



18-280 UlS Routine Descriptions 
UIS$SET-CLIP 
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UIS$SET^CLOSE^ST 

Specifies a user-requested AST routine to be executed when the "Delete" 
menu item is selected in the Window Options Menu. 


Format 

UIS$SET_CLOSE_AST wd-id [,astadr [,astprm]] 


Returns 

UIS$SET_CLOSE_AST signals all errors; no condition values are returned. 


Arguments 


wd—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


astadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
read only 
by reference 


AST routine. The astadr argument is the address of a procedure entry mask 
of a user-supplied subroutine that is called at AST level whenever the delete 
item in the Window Options Menu is selected. See the Description section 
for more information about disabling close AST routines. 


astprm 

VMS Usage: 
type: 
access: 
mechanism: 


user_arg 

Iongword (unsigned) 
read only 
by reference 


AST parameter. The astprm is the address of a single argument or data 
structure, such as an array or record, to be used by the AST routine. Calls to 
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UIS$SET_CLOSE_-AST in FORTRAN application programs should be coded 
as follows: %REF(%LOC(astprm)). 


Description 

Typically, UlS$SET_CLOSE_AST is called to override the default window 
closing behavior. If a CLOSE AST routine are not specified, UIS calls 
UIS$CLOSE—WINDOW by default. If this behavior is not sufficient, the 
application program may call UIS$SET_CLOSE_AST with its own close 
routine. 

If the application has previously enabled close ASTs, but no longer needs 
to do special tasks when closing a window, it may specify UIS$CLOSE_ 
WINDOW as the astadr parameter to reenable the default UIS action. 

Closing a window may be completely disabled in any of the following ways: 

• Specify 0 in the astadr argument 

• Specify only the w d i d argument. 

• Omit the astadr and astprm arguments. 

When window closing is disabled, the "Delete" menu item in the Window 
Options Menu changes from boldface to lightface. 

To reenable the default window closing behavior, specify 

UIS$C—DEFAULT—CLOSE as the astadr argument in a subsequent call to 

UIS$SET-CLOSE-AST. 
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UIS$SET^COLOR 

Sets a single entry in the virtual color map associated with the virtual display. 
The color map entry is an RGB value for a specific color. 


Format 

UIS$SET--COLOR vd-id, index, R, G, B 


Returns 

UIS$SET_COLOR signals all errors; no condition values are returned. 


Arguments 


vd-Jd 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$ CREATE—DISPLAY for 
more information about the vd_id argument. 


index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Color map index. The index argument is the address of a longword value 
that identifies an entry in the color map. If the index exceeds the maximum 
index for the associated color map, an error is signaled. 


R 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Red value. The R argument is the address of an f—floating point number that 
defines the red value. The red value is in the range of 0.0 to 1.0, inclusive. 
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G 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Green value. The G argument is the address of an f—floating point number 
that defines the green value. The green value is in the range of 0.0 to 1.0, 
inclusive. 


B 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Blue value. The B argument is the address of an f—floating point number 
that defines the blue value. The blue value is in the range of 0.0 to 2.0, 
inclusive. 


Description 

To maximize compatibility between monochrome and color display devices, 
U1S$SET—COLOR performs an internal transformation of the red, green, and 
blue values when the actual workstation display is monochromatic. 

A single intensity value in the range of 0.0 to 1.0 is derived using the 
following formula. 

I = (0.30*R) + (0.59*G) + (0.11*B) 

On monochrome systems, this derived intensity value is then compared to 
0.5. If the value is greater than or equal to 0.5, then white pixels are written. 
Otherwise, black pixels are written. 




Illustration 


Color Value 
Color Value 
Color Value 
Color Value 
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Red Green Blue 

3 

4 

5 

6 

7 

8 
9 

t 

Color Map Index 

ZK-5443-86 
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UIS$SET_COLORS 


Sets more than one color entry in the virtual color map. 


Format 

UIS$SET_COLORS vd—id, index, count, r—vector, g—vector, 

b^vector 


Returns 

UIS$SET_COLORS signals all errors; no condition values are returned. 


Arguments 


vcL-id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


index 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Starting color map index. The index argument is the address of a Iongword 
that defines the starting index in the virtual color map. 

If the index exceeds the maximum index for the virtual color map, an error is 
signaled. 


count 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 
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Number of indices. The count argument is the address of a longword that 
contains the number of indices including the starting index of the color map 
If the count exceeds the maximum number of virtual color map entries, an 
error is signaled. 


t—vector 


VMS Usage: 
type: 
access: 
mechanism: 


vector_longword—signed 
f_floating 
read only 
by reference 


Red values. The r_vector argument is the address of an array of f_floating 
point numbers that define the red values. 


g—vector 
VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—signed 
f_floating 
read only 
by reference 


Green values. The g_vector argument is the address of an array of f—floating 
point numbers that define the green values. 


b—vector 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—signed 
f—floating 
read only 
by reference 


Blue values. The b—vector argument is the address of an array of f—floating - 
point numbers that define the blue values. 


Description 

On color and intensity systems, color map updates of greater than 
approximately 80 entries cause visible screen disturbance, which appears 
as a black bar across the top inch of the display screen. This anomaly is 
caused by a hardware restriction that precludes large lookup table updates 
within the vertical blanking interval of the raster scan. 



18-288 UlS Routine Descriptions 
UIS$SET_COLORS 



Ti 




Red ( 



t 


Color Map Index 


ZK 5442-86 




UlS Routine Descriptions 18-289 

UIS$SET_EXPAND_ICON_AST 


UIS$SET-»EXPAND_ICON_AST 

Specifies a user-requested AST routine to be executed whenever an icon is to 
be replaced with its associated display viewport. 


Format 

UIS$SET_EXPAND_ICON_AST wd-id [,astadr [,astprm]] 


Returns 

UIS$SET_JEXPAND_ICON_AST signals all errors; no condition values are 
returned. 


Arguments 


wd-Jd 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more iniformaton about the wd_id argument. 


astadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
read only 
by reference 


AST routine. The astadr argument is the address of an entry mask of a user- 
written procedure called at AST level whenever the "Expand Icon" menu 
item in the Window Options Menu is selected. 


To cancel the AST-enabling request of UIS$SET_EXPAND_ICON_AST, 
specify 0 in the astadr argument. 


astprm 
VMS Usage: 
type: 
access: 
mechanism: 


user—arg 

iongword (unsigned) 
read oniy 
by reference 
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AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record, to be passed to the AST routine. 
Calls to UIS$SET_EXPAND_ICON_AST in VAX FORTRAN application 
programs should be coded as follows: %REF(%LOC(astprm)). 


Description 

The user interface for replacing an icon with a display viewport can be 
disabled by calling UIS$SET_EXPAND_ICON_AST with the wd_id 
argument only. 

To reenable the default behavior of UIS$SET_EXPAND_ICON_AST, specify 
the constant UIS$C_DEFAULT_EXPAND_ICON in the astadr argument. 
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UIS$SET_FILI_PATTERN 

Sets the current fill pattern used in area fill operations. 


Format 

UIS$SET_FILL -PATTERN vd-id, iatb, oatb [,index] 


Returns 

UIS$SET_FILL—PATTERN signals all errors; no condition values are 
returned. 


Arguments 


vd—id 


VMS Usage; 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd id argument. 


iatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Input attribute block number. The iatb argument is the address of a 
longword integer value that identifies an attribute block to be modified. 
Either the attribute block 0 or a previously modified attribute block may be 
specified. 


oatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 
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Output attribute block number. The oatb argument is the address of a 
longword integer value that identifies the newly modified attribute block that 
controls the fill pattern. 

index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Index of the fill pattern in the current font. The index argument is the 
address of a longword value that identifies a character glyph in the current 
font. The value specified in the index argument modifies the current fill 
pattern index specified in the input attribute block. 

If the index argument is not specified, fill patterns are disabled. 


Description 

The fill pattern is expressed as a character glyph in the font currently 
associated with the same attribute block. There are usually several font 
files reserved to store fill patterns (rasters). At present, fill patterns of width 
greater than 32 bits are not supported. 

UIS provides a font file containing a variety of fill patterns. This font file is 
referenced by UIS$FILL—PATTERNS. Entries in the UIS$FILL—PATTERNS 
font are symbolically referenced by the symbols PATT$C—xxx. 

To get a listing of all fill pattern symbols available to application programs, 
see Section 6.6 for a list of symbol definition files. 

Refer to Appendix D for illustrations showing each UIS fill pattern. 


Example 


CALL UIS$SET_FONT(VD_ID.0,1,’UIS$FILL_PATTERNS’) O 
CALL UIS$SET_FILL_PATTERN(VD_ID,1,1,PATT$C_VERT1_7) © 
CALL UIS$SET_F0NT(VD_ID.1.2,’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD_ID,2.2.PATT$C_H0RIZ1_7) 


CALL UIS$CIRCLE(VD.ID.1,10.0,10.0,8.0) 
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CALL UIS$ERASE(VD_ID) 

CALL UIS$PLOT(VD_ID.2,2.0.2.0,18.0.2.0.18.0.18.0.2.0,18.0, 

2 2 . 0 , 2 . 0 ) 

CALL UIS$CIRCLE(VD_ID.1,10.0.10.0,8.0) 

CALL UIS$PL0T(VD_ID,2.2.0,2.0,18.0.2.0,18.0,18.0,2.0,18.0, 

2 2 . 0 , 2 . 0 ) 


The preceding example fills the circle with a vertical fill pattern and a square 
with a horizontal fill pattern. Please note that enabling fill patterns for a 
single graphic object is a two-step process O ®. 

1. Modify the font attribute specifying the fill pattern file in SYS$FONT. 
Use the logical name UIS$FILL-PATTERNS. 

2. Modify the fill pattern file specifying the fill pattern to be used. 
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UIS$SET_FONT 

Specifies the fonts to be used in text drawing (UIS$TEXT) and area filling 
(UIS$PLOT). 


Format 

UIS$SET_FONT vd—id, iatb, oatb, font—id 


Returns 

UIS$SET_FONT signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
value that uniquely identifies the virtual display. See U1S$CREATE_ 
DISPLAY for more information about the argument vd_id. 


iatb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read only 
by reference 


Input attribute block number. The iatb argument is the address of a 
longword value that specifies the attribute block to be modified. The font 
attribute in the input attribute block is modified to reflect the new font 
file specified in the font_id argument. Either the attribute block 0 or a 
previously modified attribute block may be specified. 


oatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 
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Output attribute block number. The oatb argument is the address of a 
longword value that specifies the newly modified attribute block. 


font—id 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Font file name string. The font—id argument is the address of a character 
string descriptor pointing to a file specification that identifies the desired font. 
System font files are located in the SYS$FONT directory. Fonts should be 
specified using only the file name. You do not need to specify the file type. 


Description 

See UIS$SET_FILL-PATTERN. 
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UIS$SET^GAIN__KB_AST 

Specifies an AST routine to be executed when the specified virtual keyboard 
is attached to the physical keyboard. 


Format 

UIS$SET_GAIN-KB_AST kb-id [,astadr [,astprm]] 


Returns 

UIS$SET_GA1N_KB_AST signals all errors; no condition values are 
returned. 


Arguments 


kb-id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual keyboard identifier. The kb_id argument is the address of 
a Iongword value that uniquely identifies a virtual keyboard. See 
U1S$CREATE_KB for more information about the kb—id argument. 


astadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure mask 
read oniy 
by reference 


AST routine. The astadr argument is the address of an entry mask to a 
procedure that is called at AST level whenever a specified virtual keyboard is 
attached to the physical keyboard. 


astprm 

VMS Usage: 
type: 
access: 
mechanism: 


user—arg 

iongword (unsigned) 
read oniy 
by reference 


AST parameter. The astprm argument is the address of a single argument 
or data structure, such as an array or record, to be used by the AST routine. 
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Calls to UIS$SET_GAIN_KB_AST in FORTRAN application programs 
should be coded as follows: %REF(%LOC(astprm)). 


Description 

To disable UIS$SET_GAIN_KB_AST, omit the astadr and astprm 
arguments. 
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UIS$SET^INSERTION_POSITION 


Positions the editing pointer in the display list. 


Format 

UIS$SET_INSERTION_POSITION 


( obj—id 1 
\ seg-id \,[flags] 
I vd-Jd ) 


Returns 

UIS$SET__INSERTION—POSITION signals all errors; no condition values are 
returned. 


Arguments 


obj—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Object identifier. The obj_id argument is the address of a longword that 
uniquely identifies an object. See the Description section for information 
about using this argument. 


sag—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Segment identifier. The seg_id argument is the address of a longword 
that uniquely identifies the segment. When seg_id is specified as the first 
argument, the second argument is not specified. See the Description section 
for information about using this argument. See also UIS$BEGIN—SEGMENT 
for more information about the seg—id argument. 
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vd-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See the Description section for 
information about using this argument. See also UIS$CREATE_DISPLAY for 
more information about the vdlid argument. 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
read only 
by reference 


Flags. The flags argument is the address of a longword mask whose bits 
define how entries are added to the display list. 

The following table lists the flags and their functions. 


Flags Description 

UIS$M_DL_INSERT_AT_BEGIN Inserts object before first object in the 

specified structure. 

UIS$M_DL_INSERT_AFTER_OBJECT Inserts object before specified object 

in the same segment as the specified 
object. 

UIS$M_DL_INSERT_BEFORE_OBJECT Inserts object after specified object 

in the same segment as the specified 
object. 


See the DESCRIPTION section for more information about how these flags 
are evaluated. 


Description 

UlS$SET_INSERTION—OBJECT examines different options in the flags 
argument depending on the type of object you specify in the first argument. 
The following table lists the effect of the flags on the different types of 
objects. 
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Flags Checked 

Effect 

Specifying the Virtual Display Identifier 

UIS$M_DL _INSERT_AT_BEGIN^ 

If this bit is set, the editing pointer 
is placed at the beginning of the 
root segment and all new objects are 
inserted there. If this bit is not set, 
the editing pointer is placed at the 
end of the root segment and all new 
objects are appended to the end of 
the root segment. 

Specifying the Segment Identifier 

All three bits^ 

If any bit is set, UIS$SET_ 
INSERTION-POSITION sets the 
editing pointer at the place directed 
by that bit. If no bits are set, the 
editing pointer is placed at the end 
of the specified segment and any 
new objects are appended to the end 
of the specified segment. 

Specifying the Object Identifier 

UIS$M_DL _lNSERT_AFTER_OBJECT^ 
UIS$M_DL _INSERT_BEFORE_OBJECT 

If any bit is set, UIS$SET_ 
INSERTION-POSITION sets the 
editing pointer at the place directed 
by that bit. If no bits are set, the 
editing pointer is placed at the 
specified object and any new objects 
are inserted before the specified 
object. 

llf UIS$M_DL_INSERT_BEFORE_OBJECT or UIS$M_DL_INSERT_AFTER_OBJECT are 
set, the routine signals an error. 

two bits are set, the routine signals an error. 
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UIS$SET_INTENSITIES 


Loads one or more intensity values in the virtual color map. 


Format 

UIS$SET_INTENSITIES vd—id, index, count, i—vector 


Returns 

U1S$SET_INTENSIT1ES signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read oniy 
by reference 


Starting color map index. The index argument is the address of a longword 
that identifies the starting color map index in the virtual color map. 


If an index exceeds the maximum index for the virtual color map, an error is 
signaled. 


count 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read oniy 
by reference 


Number of indices. The count argument is the address of a longword that 
defines the number of indices in the virtual color map (including the starting 
index) whose entries are to be loaded with intensity values. 
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If count exceeds the maximum number of virtual color map entries, an error 
is signaled. 

i—vector 

VMS Usage: vector_longword_signed 
type: f_floating 

access: read only 

mechanism: by reference 

Intensity values. The L_vector argument is the address of an array of 
f_floating point numbers that define the intensity values of the virtual color 
map entries. 
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UIS$SET_INTENSITY 


Loads a single entry in the virtual color map with an intensity value. 


Format 

UIS$SET_INTENSITY vdUd, index, I 


Returns 

U1S$SET_INTENSITY signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
value that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY 
for more information about the vd_id argument. 


index 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Color map index. The index argument is the address of a Iongword value 
that identifies an entry in the color map. If the index exceeds the maximum 
index for the associated color map, an error is signaled. 


/ 

VMS Usage: 
type: 
access: 
mechanism: 


floating—point 
f—floating 
read oniy 
by reference 


Intensity value. The I argument is the address of an f—floating point number 
that defines the intensity. The intensity value is in the range of 0.0 to 1 . 0 , 
inclusive. 
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Illustration 



0.75 Intensity Value 



Color Map Index 


ZK-5441-86 
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UIS$SET_KB_AST 

Associates a key strike with the execution of a user-written AST routine. 

Format 

UIS$SET_KB_AST kb—id [,astadr [,astprm] ,keybuf] 

Returns 

UIS$SET_KB_AST signals all errors; no condition values are returned. 


Arguments 

kb—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual keyboard identifier. The kb_id argument is the address of 
a longword value that uniquely identifies a virtual keyboard. See 
UIS$CREATE_KB for more information about the kb-id argument. 

astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read oniy 

mechanism: by reference 

AST routine. The astadr argument is the address of the entry mask to a 
procedure to be called at AST level whenever a key is struck. To cancel a 
previous AST-enabling request of UIS$SET_KB_AST, specify 0 as the astadr 
argument. 

astprm 

VMS Usage: user_arg 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record to be passed to the AST routine. 
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Calls to UIS$SET_KB_AST in FORTRAN application programs that use this 
argument should be coded as follows: %REF(%LOC(astprm)). 


keybuf 

VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
read only 
by reference 


Key buffer. The keybuf argument is the address of a longword buffer that 
receives the key information with the execution of each AST routine. The 
low two bytes are the key code. The key codes are based on the codes found 
in the module $SMGDEF in SYS$LIBRARY:STARLET.MLB. Bit <31 > is set 
to 1 to indicate that the key is down. The AST routine is called only on the 
downstroke of the key. The buffer is not overwritten with subsequent keys 
until the AST routine completes. 

The following table defines the bits in the high- and lower-order word. 


Field 

Symbol 

1-16 

UIS$W_KEY_CODE 

28 

UIS$V_KEY_SHIFT^ 

29 

UIS$V_KEY_CTRL^ 

30 

uis$v_key_lock1 

31 

UIS$V_KEY_DOWN 


^This symbol is returned as SET if the corresponding key on the keyboard was down when 
the input event occurred. 


Description 

The terminal emulators use this routine to get all keyboard input. Other 
applications that perform asynchronous single character input can also use 
UIS$SET_KB_AST. 

To disable UIS$SET_KB_AST, omit the astadr and astprm arguments. 
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UIS$SET_KB_ATTRIBUTES 


Modifies the keyboard characteristics. 


Format 

UIS$SET_KB_ATTRIBUTES kb-id [,enable-items] 

[, disable—items] [, click— volume] 


Returns 

UIS$SET_KB_ATTRIBUTES signals all errors; no condition values are 
returned. 


Arguments 


kb-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual keyboard identifier. The kb_id argument is the address of a 
Iongword that uniquely identifies a virtual keyboard. See U1S$CREATE_ 
KB for more information about the kb_id argument. 


enable—items 

VMS Usage: mask_iongword 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 


Keyboard characteristics to be enabled. The enable—items argument is the 
address of a Iongword mask that identifies the keyboard characteristics to be 
enabled. 


disable—items 

VMS Usage: mask—Iongword 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 
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Keyboard characteristics to be disabled. The disable_items argument is the 
address of a longword mask that identifies the keyboard characteristics to be 
disabled. 

click—volume 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Click volume level. The click_volume argument is the address of a 
longword value that modifies the keyboard click volume for keyboard 
input to this window. The value is in the range 1 to 8 , where the value 
1 is the minimum volume level, and the value 8 is the maximum volume 
level. The default volume level is controlled by the workstation setup menu 
mechanism. 


Description 

All keyboard characteristics will be in effect only when the physical keyboard 
is attached to the specified virtual keyboard. Each virtual keyboard maintains 
its own keyboard characteristics and the human interface automatically 
switches the characteristics when the keyboard is associated with another 
virtual keyboard. 

The enable and disable item lists are longword masks containing bits 
designating the characteristics to be enabled or disabled. The valid bits 
in the keyboard characteristics enable and disable masks are: 


Symbol 

Description^ 

UIS$M_KB_AUTORPT 

Enable/disable keyboard autorepeat 

UIS$M_KB_KEYCLICK 

Enable/disable keyboard key click 

UIS$M_KB_UDF6 

Enable/disable up button transitions for [f6] to |fio| keys 

UIS$M_KB_UDF11 

Enable/disable up button transitions for |F11 1 to 
|Fi4| keys 

UIS$M_KB_UDF17 

Enable/disable up button transitions for |F17| to 
|F20| keys 

UIS$M_KB_HELPDO 

Enable/disable up button transitions for I HELP | and 
|DO| keys 

UIS$M_KB_UDE1 

Enable/disable up button transitions for [HI to [k] keys 


^ By default down button transitions are enabled. 
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Symbol 

Description^ 

UIS$M_KB_ARROW 

UIS$M_KB_KEYPAD 

Enable/disable up button transitions for arrow keys 

Enable/disable up button transitions for numeric 
keypad keys 

^By default down button transitions are enabled. 


Example 


enable_items=UIS$M_KB_HELPDO .OR. UIS$M_KB_UDE1 .OR. UIS$M_KB_ARR0W 

disable_items=UIS$M_KB_AUTORPT .OR. UIS$M_KB_KEYCLICK 

CALL UIS$SET_KB_ATTRIBUTES(KB_ID. ENABLE_ITEMS,DISABLE_ITEMS) 


The preceding example describes how to enable and disable more than one 
keyboard characteristic at a time. 
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UIS$SET_KB_COMPOSE2 

Loads a two-stroke compose sequence table for the specified virtual 
keyboard. 

Format 

UIS$SET_KB_COMPOSE2 kb-id [,table, tablelen] 

Returns 

UIS$SET_KB_COMPOSE2 signals all errors; no condition values are 
returned. 

Arguments 

kb-id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual keyboard identifier. The kb_id argument is the address of 
a Iongword value that uniquely identifies a virtual keyboard. See 
UIS$CREATE_KB for more information about the kb_id argument. 

table 

VMS Usage: vector_iongword—unsigned 
type: iongword array 

access: read oniy 

mechanism: by reference 

Compose table. The table argument is the address of an array that identifies 
the compose table. If no table is specified, the system default table is 
reestablished. 

tablelen 

VMS Usage: word—unsigned 
type: word 

access: read only 

mechanism: by reference 

Length of the compose table in bytes. The tablelen argument is the address 
of word that defines the length of the compose table in bytes. 
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Description 

You can use compose sequences to create characters that do not exist as 
standard keys on your keyboard. 

Two-stroke sequences can be used on all keyboards except the North 
American keyboard. Two-stroke sequences do not use the I compose I key. 
Although faster to use than the three-stroke sequence, two-stroke sequences 
are limited to sequences starting with the following nonspacing diacritical 
marks: grave accent ('), acute accent ( ), circumflex accent ("), tilde mark 
(~ ), diaresis mark ( “), and the ring mark. Instead of using the I com pose I key, 
as in a three-stroke sequence, you use a nonspacing diacritical mark to 
initiate the two-stroke sequence. You then enter a standard character that, 
together with that diacritical mark, results in a valid compose sequence. 

Please refer to the MicroVMS Workstation Video Device Driver Manual for 
a description of this table and the macros to generate it. An application 
wishing to modify a table can use these macros to build a new table. 

The MicroVMS Workstation contains a copy of the DIGITAL standard two- 
stroke compose table residing within the driver. This can be changed by 
performing a call to the SYS$QIO system service to the QVSS device driver. 

NOTE: DIGITAL standard two-stroke compose sequences are not supported 
on the North American keyboard. 
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UIS$SET_KB_COMPOSE3 

Loads a three-stroke compose sequence for the specified virtual keyboard. 


Format 

UIS$SET_KB-COMPOSE3 kbUd [,table, tablelen] 


Returns 

UIS$SET_KB_COMPOSE3 signals all errors; no condition values are 
returned. 


Arguments 

kb—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual keyboard identifier. The kb_id argument is the address of 
a Iongword value that uniquely identifies a virtual keyboard. See 
UIS$CREATE__KB for more information about the kb_id argument. 

table 

VMS Usage: vector_iongworcL.unsigned 
type: iongword array 

access: read oniy 

mechanism: by reference 

Compose table. The table argument is the address of an array that identifies 
the compose table. 

tablelen 

VMS Usage: word—unsigned 
type: word 

access: read only 

mechanism: by reference 

Length of the compose table in bytes. The tablelen argument is the address 
of a word that defines the length of the compose table in bytes. 
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Description 

You can use compose sequences to create characters that do not exist as 
standard keys on your keyboard. There are two types of compose sequences: 
two-stroke sequences and three-stroke sequences. 

Three-stroke sequences can be used on all keyboards. They are performed 
by first pressing the I compose I key and then pressing two standard keys. 

Please refer to the MicroVMS Workstation Video Device Driver Manual for 
a description of this table and the macros to generate it. An application 
wishing to modify a table can use these macros to build a new table. 

The MicroVMS Workstation contains a copy of the DIGITAL standard three- 
stroke compose tables residing within the driver. This can be changed by 
performing a call to the SYS$QIO system service to the QVSS device driver. 
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UIS$SET_KB_KEYTABLE 

Loads a keyboard equivalence table for the specified virtual keyboard. 


Format 

UIS$SET_KB_KEYTABLE kb-id [,table, tablelen] 


Returns 

UIS$SET_KB_KEYTABLE signals all errors; no condition values are returrled. 


Arguments 

kb^id 

VMS Usage; identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual keyboard identifier. The kb_id argument is the address of a 
Iongword that uniquely identifies a virtual keyboard. See UIS$CREATE_ 
KB for more information about the kb_id argument. 

table 

VMS Usage: vector_iongword—unsigned 
type: Iongword array 

access; read only 

mechanism: by reference 

Keyboard table. The table argument is the address of an array that contains 
the keyboard table. If no table is specified, the system default table is 
reestablished. 

tablelen 

VMS Usage: word—unsigned 
type: word 

access; read only 

mechanism: by reference 

Length of the keyboard table. The tablelen argument is the address of a 
word that specifies the length of the keyboard table in bytes. 
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Description 

UIS$SET_KB_KEYTABLE lets you change the ASCII character returned by a 
key on the keyboard. 

Keyboard Table Description and Macros 

Please refer to the MicroVMS Workstation Video Device Driver Manual for a 
description of the table and the macro to build it. An application wishing to 
modify a table can use these macros to build a new table. 

Keyboard Table Modification Using the Programming Interface 

The MicroVMS Workstation contains a copy of the North American table 
established as the default keyboard table. You can modify the default 
keyboard table at the driver (QVSS) level by calling the SYS$QIO system 
service. 

Keyboard Table Modification Through the User Interface 

If you want to create a keyboard table that any user can load using the 
Workstation Setup menus, see the command file DVORAK.COM in the 
directory SYS$EXAMPLES. It provides an example of how to create, compile, 
and install the DVORAK simplified keyboard. The user interface can be used 
to modify the default key table. 
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UIS$SET_LINE_STYLE 

Sets the line style bit vector. 


Format 

UIS$SET_LINE_STYLE vd-id, iatb, oatb, style 


Returns 

U1S$SET_L1NE—STYLE signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd—id argument. 

iatb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
Iongword integer that specifies an attribute block to be modified. 

oatb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
Iongword integer that specifies the newly modified attribute block that 
controls the line style. 
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Style 

VMS Usage: mask—longword 
type: longword 

access: read only 

mechanism: by reference 

Line style bit vector. The style argument is the address of a longword bit 
vector that specifies whether to use foreground or background when drawing 
each pixel. It is repeated as many times as necessary to draw all the pixels in 
the line. 


Example 


CALL UIS$SET_LINE_STYLE(VD_ID.0.1.’FFFFFFFO’x) 
CALL UIS$PL0T(VD_ID.1.0.0.0.0.5.0.20.0) 

CALL UIS$SET_LINE_STYLE(VD_ID.0.2.’FFFOFFFO’x) 
CALL UIS$PL0T(VD_ID.2.0.0.0.0.10.0.20.0) 


The preceding example produces the first two dashed lines shown in the next 
section. 
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Screen Output 



ZK-5285-86 
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UIS$SET_LINE_WIDTH 

Sets the width of lines drawn on the screen. 

Format 

UIS$SET-LINE_WIDTH vd-id, iatb, oatb, width [,mode] 

Returns 

UIS$SET_LINE—WIDTH signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 

iatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
longword that specifies an attribute block to be modified. 

oatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
longword that specifies an attribute block that controls line width. 
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width 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Width of the line. The width argument is the address of an f—floating point 
number that defines the line width. See the DESCRIPTION section for more 
information about specifying the line width with UIS$C—WIDTH-WORLD. 
The default value is 1. 


mode 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
iongword (unsigned) 
read only 
by reference 


Mode. The mode argument is the address of a longword that indicates 
whether the line width should be interpreted as an absolute number of 
pixels or as an x world coordinate width. Specify the mode using one of the 
following constants: 

• UIS$C-WIDTH-PIXELS 


• UIS$C-WIDTH-WORLD 


If mode is not specified, line width is interpreted as an absolute number of 
pixels (UIS$C_WIDTH-PIXELS). 

See DESCRIPTION for more information about the constant UIS$C— 
WIDTH-WORLD. 


Description 

The line width is specified as a floating point number that is multiplied by 
the normal line width to produce line width actually drawn. 

If you specify 0.0 in the width argument when the mode argument is 
UIS$C—WIDTH—WORLD, the minimum line width is generated. 
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Example 


CALL UIS$SET_LINE_WIDTH (VD.ID, 0,1.2.0. VfDPL$C_WIDTH_WORLD) 
CALL UIS$PLOT(VD_ID.1,0.0.0.0.10.0,20.0) 

CALL UIS$SET_LINE_WIDTH(VD_ID.0,2.4.0.WDPL$C_WIDTH_WORLD) 
CALL UIS$PL0T(VD_ID.2.0.0,0.0,15.0,20.0) 


The preceding example describes how to specify line width as x world 
coordinate width. 
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Screen Output 
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UIS$SET_LOSE_KB_AST 

Enables an AST routine that is executed when the specified virtual keyboard 
is detached from the physical keyboard. 

Format 

UIS$SET_LOSE_KB_AST kb-id [,astadr [,astprm]] 

Returns 

UIS$SET_LOSE_KB_AST signals all errors; no condition values are 
returned. 

Arguments 

kbUd 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual keyboard identifier. The kb_id argument is the address of a 
Iongword that uniquely identifies a virtual keyboard. See U1S$CREATE_ 

KB for more information about the kb—id argument. 

astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

AST routine. The astadr argument is the address of the entry mask to 
a procedure that is called at AST level whenever the virtual keyboard is 
disconnected from the physical keyboard. 

astprm 

VMS Usage: user_arg 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record, to be passed to the AST routine. 
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Calls to UIS$SET_LOSE_KB_AST in VAX FORTRAN application programs 
should reference this argument as follows: %REF(%LOC(astprm)). 


Description 

To cancel the AST-enabling request of UIS$SET_LOSE_JKB_AST, specify 0 
in the astadr argument or omit the astadr and astprm arguments. 



18-326 UlS Routine Descriptions 
UIS$SET_MOVE_INFO_AST 


UIS$SET^MOVE_INFO_AST 

Enables an AST routine execution whenever the specified display viewport 
has been moved. 


Format 

UIS$SET_MOVE_INFO_AST wd-id, [,astadr [,astprm]] 


Returns 

UlS$SET_MOVE_INFO—AST signals all errors; no condition values are 
returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 


astadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
read oniy 
by reference 


AST routine. The astadr argument is the address of an entry mask to a 
procedure that is called at AST level whenever the specified display viewport 
is moved. 


astprm 
VMS Usage: 
type: 
access: 
mechanism: 


user—arg 

longword (unsigned) 
read only 
by reference 


AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record, that is passed to the AST routine. 
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Calls to UlS$SET_MOVE_INFO_AST in VAX FORTRAN application 
programs should code this argument as follows: %REF(%LOC(astprm)). 


Description 

A MOVE notification AST can be used when an image needs to keep several 
display viewports in a particular arrangement. If one is moved, the AST 
routine can recreate the other display viewports in the correct positions 
around the moved viewport. 

To cancel the AST-enabling request of UlS$SET_MOVE_INFO_AST, 
perform any of the following actions: 

• Specify the wd_id argument only. 

• Specify 0 in the optional astadr argument. 

• Omit the astadr and astprm arguments. 
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UIS$SET_POINTER_AST 

Allows an application to find out when the pointer is moved within, into, 
and out of a specified rectangle in the display window. 

Format 

UIS$SET_POINTER_AST vd-id, wdUd [,astadr [.astprm]] 

[,Xp y,, X 2 , Yzl lexitastadr 
[,exitastprm]] 


Returns 

UIS$SET_POINTER_AST signals all errors; no condition values are 
returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 
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AST routine. The astadr argument is the address of the entry mask to a 
procedure that is called at AST level whenever the pointer is moved within a 
rectangle in the virtual display. 

To cancel the AST-enabling request of UIS$SET_POINTER_AST for this 
argument only, specify 0 in the astadr argument and the coordinates of the 
rectangle. 

astprm 

VMS Usage: user_arg 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record, passed to the AST routine. Calls to 
UIS$SET_POINTER_AST in VAX FORTRAN application programs should 
be coded as follows: %REF(%LOC(astprm)). 

Xi, Yi, X2, y2 

VMS Usage: floating-point 
type: f_floating 

access: read only 

mechanism: by reference 

World coordinates of the rectangle. The Xj and jj arguments are the 
addresses of f_floating point numbers that define the lower-left comer of 
the rectangle of the display window. The X 2 and y 2 arguments are the 
addresses of f_floating point numbers that define the upper-right corner of 
the rectangle of the display window. 

If no rectangle is specified, the entire display window is assumed. 

To cancel an AST-enabling request, specify 0 in either the astadr or the 
exitastadr arguments or both and the coordinates of the rectangle. 

exitastadr 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

Exit AST routine. The exitastadr argument is the address of the entry mask 
to a procedure that is called at AST level whenever the pointer leaves the 
rectangle. 

To cancel the AST-enabling request of UIS$SET_POINTER_AST for the 
EXIT AST routine only, specify 0 in the exitastadr argument and the 
coordinates of the rectangle. 
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exitastprm 
VMS Usage: 
type: 
access: 
mechanism: 


user_arg 

longword (unsigned) 
read only 
by reference 


Exit AST parameter. The exitastprm argument is the address of a single 
argument or data structure, such as an array or record, to be passed to the 
AST routine. Calls to UlS$SET_POINTER_AST in FORTRAN application 
programs should be coded as follows: %REF(%LOC(exitastprm)). 


Description 

The Set Pointer AST routine also allows an application to keep track of the 
pointer in its own way. This routine can be called any number of times for 
different rectangles. 

Note that an application need not enable both AST routines. It may specify 
one or the other. 

UIS$SET_POINTER_AST can be used by the application to highlight the 
display or some other application-specific function, as the user moves the 
pointer over specific areas of the display window. This might be used to 
define a number of regions within a menu, and execute an AST routine 
when the pointer enters or leaves any of these regions. 

If both AST routines are enabled and the value 0 is specified in the astadr 
argument, the first AST routine is canceled. 

To disable AST-enabling behavior for pointers entering a region, omit the 
astadr and astprm arguments. 

To disable AST-enabling behavior for pointers leaving a region, omit the 
exitastadr and exitastprm arguments. 

Pointer Region Priorities 

UIS pointer regions are placed on the VAXstation screen in the order in 
which they are created. Therefore, if you create two overlapping viewports, 
and then use UIS$SET_POINTER_PATTERN, UIS$SET_BUTTON_AST, 
or UIS$SET_JPOINTER_AST to define different pointer patterns for each 
viewport, the correctness of the result will depend on the order in which 
you both created the viewports and defined the cursor regions. For example, 
if you create the viewports and define the cursor patterns in the following 
manner, the viewport 1 cursor pattern will have a higher priority than 
viewport 2 cursor pattern in the overlapping region. 
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1. Create viewport 1 

2. Create overlapping viewport 2 

3. Define viewport 2 cursor pattern 

4. Define viewport 1 cursor pattern 

The preceding example causes the unexpected result that the viewport 1 
cursor pattern will take priority over the viewport 2 cursor pattern in the 
overlapping region. This problem can be corrected by creating the viewports 
and defining the cursor patterns in the same order. To correct the problem, 
create the viewports and define cursor patterns in the following order: 

1. Create viewport 1 

2. Define viewport 1 cursor pattern 

3. Create overlapping viewport 2 

4. Define viewport 2 cursor pattern 

The solution is for either UIS or your application to always pop the viewport 
before defining the cursor region for it. 
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UIS$SET^POINTER^PATTERN 

Allows an application to specify a special pointer cursor pattern for a 
specified rectangle in the virtual display. 


Format 


UIS$SET_POINTER_PATTERN vd-id, wd-id 

[,pattern^array, 
pattern—count, activex, 
activey] [, x„ y„ X2, yj 
[Mgs] 


Returns 

UIS$SET_POINTER_PATTERN signals all errors; no condition values are 
returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd__id argument. 
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pattern—array 

VMS Usage: vector_word_unsigned 
type: word—unsigned 

access: read only 

mechanism: by reference 

16- X 16-bit cursor pattern. The pattern-array argument is the address of 
one or more 16-bit arrays of 16 words that represents a bitmap image of the 
cursor pattern. 

You can define two patterns that are executable on color and intensity 
systems using two arrays—a color plane and a mask plane. However, 
monochrome systems use a single array to specify the cursor pattern. 

If two arrays are specified in an application running on a single-plane system, 
the first array is used. 


NOTE: The bitmap image of the new pointer pattern is mapped in reverse 
order to the display screen. 


pattern—count 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
longword (unsigned) 
read only 
by reference 


Number of 16- x 16-bit cursor patterns defined. The pattern—count 
argument is the address of a longword that contains the number of cursor 
pattern arrays defined in the pattern—array argument. 


activex, activey 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read oniy 
by reference 


The activex and activey arguments are used to specify the actual bit in the 
cursor pattern that should be used to calculate the current pointer position. 
The arguments are expressed as bit offsets from the lower-left comer of the 
cursor pattern. 


xi, yi, X2, y2 

VMS Usage: floating-point 
type: f—floating 

access: read oniy 

mechanism: by reference 

World coordinates of the rectangle in the virtual display. The Xj and yj 
arguments are the addresses of f—floating point numbers that define the 
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lower-left comer of the rectangle in the display window. The X 2 and y 2 
arguments are the addresses of f_floating point numbers that define the 
upper-right comer of the rectangle in the display window. 


flags 

VMS Usage: 
type: 
access: 
mechanism: 


longword_mask 
longword (unsigned) 
read only 
by reference 


Flags. The flags argument is the address of a longword mask whose bits 
determine whether or not the cursor is confined to the display window 
rectangle. 

When specified, UIS$M_BIND_P01NTER sets the appropriate bit in the 
mask. 


Description 

UIS$SET_POINTER_PATTERN allows an application to specify a special 
pointer pattern to be used when the pointer is within the display window 
region specified by the optional rectangle. If no rectangle is given, then the 
entire display window is assumed. This function can be called any number 
of times for different rectangles. 

To disable UIS$SET_POINTER—PATTERN, omit the pattern—array, 
pattern—count, activex, activey, and flags arguments. 
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UIS$SEUOINTER^POSmON 

Specifies a new current pointer position in world coordinates. It is only 
effective if the new pointer position is within the specified display window 
and visible. 


Format 

sfaftys=UIS$SEUOINTER_POSITION vd-id, wd-id, x, y 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


boolean 
longword 
write only 
by value 


Boolean value returned in a status variable or RO (VAX MACRO). A status of 
1 is returned, if the operation is successful, otherwise a 0 is returned. 

UIS$SET_POINTER_POSITION signals all errors; no condition values are 
returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd . id argument. 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE— 
WINDOW for more information about the wd—id argument. 
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VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

World coordinates of the new pointer position. The x and y arguments 
are the addresses of f_floating point numbers that define the new pointer 
position. 
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UIS$SET_POSITION 

Sets the current position for text output. The current position is the point of 
alignment on the baseline of the next character to be output. 


Format 

UIS$SET_POSITION vd-id, x,y 


Returns 

UlS$SET_POSITION signals all errors; no condition values are returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd__id argument. 


x,y 

VMS Usage: 
type: 
access: 
mechanism: 


floating—point 
f—floating 
read oniy 
by reference 


X and y world coordinate position. The x and y arguments are the addresses 
of f—floating point numbers that define the current position for text output. 
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Example 


REAL*4 Y 
DATA Y/4.0/ 


DO 1=1,5 

CALL UIS$SET_POSITION(VD_ID.FLOAT(I).Y) 
CALL UIS$PL0T(VD_ID.1.0.0.Y.FL0AT(I).Y) 
Y=Y-1.0 

CALL UIS$SET_FONT(VD_ID.1.1,’MY_F0NT_11’) 
CALL UIS$TEXT(VD_ID.l,’Full speed ahead!’) 
ENDDO 



ZK-5386-86 
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UIS$SET_RESIZE-AST 

Specifies a user-requested AST routine to be executed when a display 
window has been resized using the user interface. 

Format 

UIS$SET_RESIZE_AST vd-id, wd-id [,astadr [,astprm]] 

[,new—abs—x, new^abs—y] 

[,new—width, new—height] 
[,new—wc—Xp new—wc—yp 
new—wc—X2, new—wc—y2] 

Returns 

UIS$SET_RESIZE_AST signals all errors; no condition values are returned. 

Arguments 

vd-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 
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astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

AST routine. The astadr argument is the address of the entry mask of a 
procedure that is called at AST level whenever the "Change the size" item 
in the Window Options Menu is selected and a display window has been 
resized. 

( 

See the Description section for information about disabling 
UIS$SET_RESIZE_AST. 

astprm 

VMS Usage: user_arg 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record, to be passed to the AST routine. 
Calls to UIS$SET_RESIZE__AST in FORTRAN application programs should 
be coded as follows: %REF(%LOC(astprm)). 

nevK-abs—x, new^abs—y 
VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Absolute device coordinate pair. The new—abs_x and new—abs—y 
arguments are the addresses of f—floating point longwords that receive 
the exact location of the newly resized display window in centimeters. 

new—width, new—height 
VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Width and height of the resized window. The new—width and new—height 
arguments are the addresses of f—floating point longwords that receive the 
dimensions of the newly resized display window in centimeters. 
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new—wc—Xi, new—wc—Yi, new-.wc—X2, #ieiv_ivc_y2 

VMS Usage: floating-point 

type: f—floating 

access: write only 

mechanism: by reference 

World coordinates of the resized window. The new—wc—Xj and 
new—wc—Yi arguments are the addresses of f—floating point longwords that 
receive the world coordinates of the lower-left corner of the newly resized 
display window. The new—wc—X2 and new—wc—y2 arguments are the 
addresses of f—floating point longwords that receive the world coordinates of 
the upper-right comer of the newly resized display window. 


Description 

Typically, a call to UIS$SET—RESIZE—AST in an application program 
indicates that the default resizing behavior is to be overridden. 

By default, if a resize AST has not been enabled in an application program, 
UIS calls UIS$RESIZE-WINDOW. If this behavior is not sufficient, the 
application program may call UIS$SET—RESIZE—AST with its own resize 
routine. 

To reenable the default behavior, specify UIS$C—DEFAULT—RESIZE as the 
astadr argument in a subsequent call to UIS$SET—RESIZE—AST. 

Resizing a window may be completely disabled in the following ways: 

• By specifying the required wd—id argument and a value of 0 in the 
astadr argument 

• By specifying only the required wd—id argument 

• Omit the astadr and astprm arguments. 

When window resizing is disabled, the option, "Change the size" displayed 
in the Window Options Menu changes from boldface to halftone. 

The parameters for the resized window's new location, dimensions, and 
world coordinate range will not be overwritten with subsequent values until 
the AST has completed. 
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Example 


VD_ID=UIS$CREATE_DISPLAY(1.0.1.0.40.0.40.0.15.0.15.0) O 
WD_ID=UIS$CREATE_WINDOW(VD_ID.’SYS$W0RKSTATI0N’.’RESIZE’. 

2 5.0.5.0.25.0.25.0) © 


CALL UIS$SET_RESIZE_AST(VD_ID.WD.ID.RESIZE.ME.0.NEW_ABS_X.NEW_ABS_Y. 
2 NEW_WIDTH.NEW.HEIGHT.NEW_WC_X1.NEW_WC_Y1. 

2 NEW_WC_X2.NEW_WC_Y2) © 

CALL SYS$HIBER() 


END !end of main program 

SUBROUTINE RESIZE.ME O 

CALL UIS$RESIZE_WINDOW(VD_ID.WD_ID,NEW_ABS_X.NEW_ABS_Y.,. 
2 1.0,1.0,40.0.40.0) © 

RETURN 

END 


In the preceding example, the call to UIS$CREATE—DISPLAY O establishes 
the initial viewport size as a square. 

The coordinate space of the initial display window is defined to be a subset 
of the virtual display ©. When the original window is displayed it will show 
only a portion of the virtual display. 
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The call to UIS$SET_RESIZE_AST @ indicates that the program will 
override the default window resizing operation by enabling a user-written 
AST routine RESIZE _ME O. 

The parameter list of UIS$RESIZE—WINDOW @ indicates how the resize 
operation is redefined. The absolute position and size of all viewports will 
default as usual to the final position and dimensions of the stretchy box. 

However, the world coordinate range of the newly resized window is 
defined explicitly as the coordinate range of the virtual display. All newly 
resized windows will show the entire virtual display. If you tried to resize 
a previously resized window, you would still see the contents of the entire 
virtual display. 

Distortion of objects displayed in the viewport will occur whenever the 
aspect ratio of the newly resized viewport does not equal the aspect ratio of 
the newly resized display window. 
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UIS$SET_SHRINK_TO_ICON_AST 

Specifies a user-requested AST routine to be executed whenever a display 
viewport is shrunk using the human interface. 


Format 

UIS$SET_SHRINK_TO_ICON_AST wd-id [,astadr [,astprm]] 


Returns 

UIS$SET_SHRINK_TO_ICON_AST signals all errors; no condition values 
are returned. 


Arguments 


wd^id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window. See U1S$CREATE_ 
WINDOW for more information about the wd_id argument. 


astadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
read oniy 
by reference 


AST routine. The astadr argument is the address of an entry mask of a 
procedure called at AST level whenever "Shrink to Icon" item in the Window 
Options Menu is selected. 


astprm 

VMS Usage: 
type: 
access: 
mechanism: 


user—arg 

Iongword (unsigned) 
read only 
by reference 


AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record, to be passed to the AST routine. 
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Calls to UIS$SET_SHRINK_TO_ICON_AST in VAX FORTRAN application 
programs should be coded as follows: %REF(%LOC(astprm)). 


Description 

The user interface for replacing a display viewport with an icon can be 
disabled by calling UIS$SET_SHRINK_TO_ICON_AST with the wd_id 
only. 

To reenable the default behavior of UIS$SET_SHRINK_TO__ICON_AST, 
specify the constant UIS$C_DEFAULT_SHRINK_TO_ICON in the astadr 
argument. 
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UIS$SET^TB__AST 

Specifies a user-requested AST routine to be executed whenever the digitizer 
lies within a specified rectangle on the tablet. 

Format 

UIS$SET_TB_AST tb-id, [,data-astadr, 

[data—astprm]], [,x—pos ,y—pos] 
[data—Xpdata—yi , data—x2, data—y2] 

[, button—astadr 

[, button—astprm], button—keybuf] 

Returns 

UIS$SET_TB_AST signals all errors; no condition values are returned. 

Arguments 

tb—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Tablet identifier. The tb_id argument is the address of a longword that 
uniquely identifies the tablet. See UIS$CREATE_TB for more information 
about the tb_id argument. 

data—astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

AST routine. The data_astadr argument is the address of an entry mask 
of a procedure that is called at AST level for each data point whenever the 
digitizer is moved within the specified active data region defined on the 
tablet. 

See the Description section for information about disabling the digitizing 
region. 
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data—astprm 

VMS Usage: user.arg 

type; longword (unsigned) 

access: read only 

mechanism: reference 

AST parameter. The data-^astprm is the address of a single argument or 
data structure, such as an array or record, to be passed to the AST routine. 
Calls to UIS$SET_TB_AST in VAX FORTRAN application programs should 
be coded as follows: %REF(%LOC(astprm)). 

x—pos,y—pos 

VMS Usage: floating-point 
type: f—floating 

access: write only 

mechanism: by reference 

Absolute device coordinate pair. The x_pos, y_pos arguments are the 
addresses of f_floating longwords that receive the current x and y tablet 
positions in centimeters relative to the lower-left corner of the tablet, when a 
data AST occurs. 

data—xi,data—Yi 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Absolute device coordinate pair. The data—X2,data— y^ arguments are the 
addresses of f—floating point numbers that define the lower-left comer of the 
data or digitizer region specified on the tablet. The data rectangle defines an 
area on the tablet in which data should be collected. 

data—X2,data—y2 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism; by reference 

Absolute device coordinate pair. The data—X2,data— y 2 arguments are the 
addresses of f_floating point numbers that define the upper-right corner of 
the data or digitizer region specified on the tablet. 

button—astadr 
VMS Usage: ast—procedure 
type: procedure entry mask 

access: read only 

mechanism; by reference 
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AST routine. The button_astadr argument is the address of an entry mask 
of a procedure that is called at AST level whenever a button is depressed or 
released within the specified active data region defined on the tablet. 


See the "DESCRIPTION" section for information about disabling the 
digitizing region. 


button—astprm 


VMS Usage: 
type: 
access: 
mechanism: 


user_arg 

longword (unsigned) 
read only 
reference 


AST parameter. The button—astprm is the address of a single argument or 
data structure, such as an array or record, to be passed to the AST routine. 
Calls to UIS$SET_TB—AST in VAX FORTRAN application programs should 
be coded as follows: %REF(%LOC(astprm)). 

button—keybuf 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Button information. The button—keybuf argument is the address of a 
longword that receives button information. 


Description 

The data rectangle specifies the active data region on the tablet. Only points 
within this rectangle are returned to the application. The data rectangle is 
specified using a centimeter coordinate system that is based at the lower-left 
comer of the tablet. 

If no data rectangle is specified, the entire tablet is assumed. 

Button AST Routines 

To disable button AST routines, specify 0 in the button—ast—rtn argument. 
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UIS$SET-_TEXT-_FORMATTING 

Sets the text formatting justification mode. 


Format 

UIS$SET_TEXT-.FORMATTING vd-id, iatb, oatb, mode 


Returns 

UIS$SET_TEXT_FORMATTING signals all errors; no condition values are 
returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 

iatb 

VMS Usage: longword—unsigned 
type: longword (signed) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
longword that identifies an attribute block to be modified. 

oatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
longword that identifies a newly modified attribute block. 
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mode 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
iongword (unsigned) 
read only 
by reference 


Text formatting mode. The mode argument is the address of a Iongword 
mask that sets the text formatting mode. The following table lists valid text 
formatting modes. 


Formatting Mode 


Function 


UIS$C_TEXT_FORMAT_LEFT 

UIS$C_TEXT_FORMAT_RIGHT 

UIS$C_TEXT_FORMAT_CENTER 

UIS$C_TEXT_FORMAT_JUSTIFY 

UIS$C_TEXT_FORMAT_NOJUSTIFY 


Left justified, ragged right 
Right justified, left ragged 

Centered line between left and right 
margin 

Justified lines, space filled to right margin 
No text justification (default) 


All other values are reserved to DIGITAL for future use. 


Description 

Text justification occurs at the end of every UIS$TEXT or UIS$MEASURE_ 
TEXT call. Text justification also occurs when a UIS$C_TEXT_NEW_LINE 
item is encountered in a UIS$TEXT or UIS$MEASURE_TEXT control list. 
The formatting mode and margins that are used are based on either the 
attribute block specified in the routine call or the last attribute block specified 
before the UIS$C_TEXT_NEW_LINE item code is encountered. 

NOTE: Lines of text that do not fit completely within the margins will 
extend beyond the margin. 
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Example 


CALL UIS$SET_TEXT_MARGINS(VD_ID,0.1,3.0.27.0.24.0) 

CALL UIS$PL0T(VD_ID.0.3.0,30.0.3.0,0.0) 

CALL UIS$PL0T(VD_ID.0,27.0,30.0.27.0.0.0) 

CALL UIS$SET_TEXT_FORMATTING(VD_ID,1.1,UIS$C_TEXT_FORMAT_JUSTIFY) 
CALL UIS$SET_ALIGNED_P0SITI0N(VD_ID.1,3.0.28.0) 

CALL UIS$SET_F0NT(VD_ID.1.2,’MY_F0NT_8’) 


DO 1= 1.4 

CALL UIS$TEXT(VD_ID.2.’What has been, may be’) 
CALL UIS$NEW_TEXT_LINE(VD_ID.2) 

ENDDO 
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UIS$SET_TEXT__MARGINS 


Sets the text margins for a line of text. 


Format 

UIS$SET-TEXT_MARGINS vd-id ,iatb ,oatb ,x ,y 

,marginUength 


Returns 

UIS$SET_TEXT_MARGINS signals all errors; no condition values are 
returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd—id argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_Jd argument. 


iatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Input attribute block number. The iatb argument is the address of a 
longword that identifies an attribute block to be modified. 


oatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Output attribute block number. The oatb argument is the address of a 
longword that identifies an attribute block. 
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x,y 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Starting margin position. The x,y arguments are the addresses of f—floating 
numbers that define a point on the margin. The margin is the minor text 
path when slope equals zero. 

margin—length 
VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Ending margin position. The margin—length is the address of an f—floating 
number that defines the distance in world coordinates from the starting 
margin to the end margin. 


Description 

Lines of text do not automatically wrap to the next line. 
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UIS$SET_TEXT_PATH 

Sets the direction of text drawing and the direction of new text lines. 


Format 

UIS$SET-_TEXT_PATH vd-id, latb, oatb, major [,minor] 

Returns 

UIS$SET_TEXT_PATH signal all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd—id argument. 

iatb 

VMS Usage: Iongword—unsigned 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a number 
that identifies an attribute block to be modified. 

oatb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
number that identifies a modified attribute block. 
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major 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Major text path. The major argument is the address of a symbol that 
identifies the major text path type. The major path of text drawing is the 
direction of text drawing along a line. See the Description section for more 
information. 


minor 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Minor text path. The minor argument is the address of a symbol that 
identifies the minor text path type. The minor path of text drawing refers to 
the direction of new text line creation. See the Description section for more 
information. 


Description 

The following table contains symbols for valid character drawing directions. 


Path 

Direction 

UIS$C_TEXT_PATH_RIGHT 

Left to right (default major text path) 

UIS$C_TEXT__PATH_LEFT 

Right to left 

UIS$C_TEXT_PATH_UP 

Bottom to top 

UIS$C_TEXT_PATH_DOWN 

Top to bottom (default minor text path) 


Example 


CALL UIS$SET_TEXT_PATH(VD_ID,0.1,UIS$C_TEXT_PATH_LEFT. 
2 UIS$C_TEXT_PATH_DOWN) 

CALL UIS$SET_FONT(VD_ID,1.1,’MY_F0NT_5’) 

CALL UIS$SET_ALIGNED_POSITION(VD_ID,1,38.0,38.0) 
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CALL UIS$TEXT(VD_ID.l.’Knowledge is power!’) 
CALL UIS$NEW_TEXT_LINE(VD_ID.l) 


The preceding example illustrates how to alter the default major text drawing 
path to produce the output shown in the next section. 



S' 


!rewop 
!rewop 
!rewop 
!rewop 
!rewop 


SIL 


egdelwon 

egdelwon 

egdelwon 

egdelwon 

egdelwon 


i 
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UIS$SET_.TEXT^SLOPE 

Sets the angle of the actual path of text drawing relative to the major path. 


Format 

UIS$SET-.TEXT_SLOPE vd-id ,iatb ,oatb,angle 


Returns 

UlS$SET_TEXT_SLOPE signals all errors; no condition values are returned. 


Arguments 

vd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd_id argument. 

iatb 

VMS Usage: iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a number 
that identifies an attribute block to be modified. 

oatb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
number that identifies an attribute block. 
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angle 

VMS Usage: floating-point 
type: f—floating 

access: read only 

mechanism: by reference 

Angle of text slope. The angle argument is the address of an f—floating point 
number that defines the angle of the actual path of text drawing relative to 
the major path measured counterclockwise in degrees. The default angle of 
text slope is 0 degrees. 


Example 


CALL UIS$SET_FONT(VD_ID,0,1.’MY_F0NT_13’) 

CALL UIS$SET_TEXT_SLOPE(VD_ID,1,2,45.0) 

DO 1=1,10 

CALL UIS$SET_ALIGNED_P0SITI0N(VD.ID,2,0.0,Y) 

CALL UISITEXT(VD.ID,2,’water seeks its own level!’) 

Y=Y-2.0 

ENDDO 

PAUSE 
DO 1=1,10 

CALL UIS$SET_ALIGNED_P0SITI0N(VD.ID.2,X,1.0) 

CALL UIS$TEXT(VD_ID,2,’water seeks its own level!’) 

X=X+2.0 

ENDDO 
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UIS$SET_WRITING-.INDEX 


Sets the writing color index for text and graphics output. 


Format 

UIS$SET_WRITING_INDEX vd-id, iatb, oatb, index 


Returns 

UIS$SET_WRITING—INDEX signals all errors; no condition values are 
returned. 


Arguments 


vd—id 

VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


iatb 


VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Input attribute block number. The iatb argument is the address of a 
Iongword integer that specifies the attribute block to be modified. 


oatb 


VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Output attribute block number. The oatb argument is the address of a 
Iongword integer that identifies the newly modified attribute block. 
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index 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Color map index. The index argument is the address of a longword integer 
that specifies a color map index. If the index exceeds the maximum index for 
the associated color map, an error is signaled. 



UlS Routine Descriptions 18-363 

UISSSET-WRITING-MODE 


UIS$SET-WRITING-MODE 


Sets the text and graphics mode. 


Format 

UIS$SET_WRITING_MODE vd-id, iatb, oatb, mode 


Returns 

UIS$SET_WRITING_MODE signals all errors; no condition values are 
returned. 


Arguments 


vd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The vd_id argument is the address of a longword 
that uniquely identifies a virtual display. See UIS$CREATE—DISPLAY for 
more information about the vd_id argument. 


iatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Input attribute block number. The iatb argument is the address of a 
longword integer that specifies an attribute block to be modified. 


oatb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Output attribute block number. The oatb argument is the address of a 
longword integer that specifies a newly modified attribute block that controls 
the writing mode. 
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mode 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Writing mode. The mode argument is the address of a longword that 
specifies the writing mode (UIS$C_MODE_xxxx). The default writing mode 
is overlay. 


Description 

Table 9-2 lists and describes all UlS writing modes. 
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UIS$SHRINK__TO_ICON 

Replaces a display viewport with its associated icon. 

Format 

UIS$SHRINK_TO_-ICON wd—id [Jcon^wd—id] [,icon—flags] 

[Jeon—name] [,attributes] 

Returns 

UIS$ SHRINK _TO_ICON signals all errors; no condition values are returned. 

Arguments 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 

icon—wd—id 

VMS Usage: identifier 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Icon window identifier. The icon_wd-id argument is the address of a 
longword that uniquely identifies an icon. 

icon—Hags 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Icon flags. The icon—flags is the address of a longword mask of flags that 
may be used to specify whether default icon behavior should be extended to 
an application-supplied icon. By default, no modifications are made to the 
application-supplied icon. The following table lists valid icon flags. 
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Flag Function 

UIS$M_ICON_DEF_JKB UIS manages keyboard ownership. If the display 

window is enabled for keyboard ownership, 
UIS$DISABLE_VIEWPORT_KB is called during 
window shrinking and UIS$ENABLE_KB is called 
during icon expansion. 

UIS$M_lCON_DEF_BODY UIS places a button AST region over the body of 

the icon window and uses that AST to trigger icon 
expansion. 

All other bits The remaining bits are set to 0 and are reserved 

to DIGITAL. 

icon—name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Icon name. The icon_naine argument is the address of a descriptor of the 
text to be used as the icon name. 

attributes 

VMS Usage: item_list—pair 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Window attributes list. The attributes argument is the address of data 
structure, such as an array or record. The attributes argument may be used 
to specify exact placement of the icon on the display screen. 

The following figure describes the structure of the window attributes list. 
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Attribute ID code 
(WDPL$C_xxx) 

Longword value for attribute 
identified in previous longword 


2nd attribute ID code 


2nd attribute value 


End of list 0 

(WDPL$C_END_OF_LIST) 


ZK-4581-85 


See UIS$CREATE—WINDOW for more information. 
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Screen Output 
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UIS$SOUND_BELL 


Actuates the keyboard bell to ring once. 


Format 

UIS$SOUND_BELL devnam [,bell—volume] 


Returns 

UIS$SOUND_BELL signals all errors; no condition values are returned. 


Arguments 


devnam 


VMS Usage: 
type: 
access: 
mechanism: 


device^ame 
character string 
read only 
by descriptor 


Device name string. The devnam argument is the address of a character 
string descriptor of the workstation device name. Specify 'SYS$WORKSTATION' 
as the default device name. 


bell—volume 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Bell volume level. The bell_volume argument is the address of a longword 
that specifies the bell volume. The bell_volume argument can be supplied 
explicitly as a number from 0 to 8 , where 0 is the most quiet; and 8 is the 
loudest. If the bell_volume argument is not specified, the default volume 
specified in the workstation setup menu is used. 


Description 

On the LK201 keyboard, the bell sound differs from a key click sound in the 
frequency and tone. 
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UIS$SOUND^CLICK 


Actuates the keyboard click sound once. 


Format 

UIS$SOUND_CLICK devnam [,click—volume] 


Returns 

UIS$SOUND_CLICK signals all errors; no condition values are returned. 


Arguments 


devnam 

VMS Usage: 
type: 
access: 
mechanism: 


device—name 
character string 
read oniy 
by descriptor 


Device name string. The devnam argument is the address of a character 
string descriptor of the workstation device name. Specify SYS$WORKSTATION 
as the device name. 


click-volume 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Key click volume level. The click_volume argument is the address of a 
Iongword that specifies the key click volume level. The click—volume 
argument is specified explicitly as a number from 0 to 8 , where 0 is the most 
quiet and 8 is the loudest. If the click—volume argument is not specified, 
the default volume is used from the workstation setup menu mechanism. 


Description 

On the LK201 keyboard, the key click sound differs from a bell sound in the 
frequency and tone. 
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UIS$TEST^KB 

Returns a boolean value indicating whether the physical keyboard is 
currently bound to the specified virtual keyboard. 


Format 

sfafus=UIS$TEST_KB kb-id 


Returns 

VMS Usage: boolean 
type: longword 

access: write only 

mechanism: by value 

Boolean value returned in a status variable or RO (VAX MACRO). The 
boolean value TRUE is returned if the physical keyboard is bound to the 
virtual keyboard, otherwise a boolean value FALSE is returned. 

UIS$TEST_KB signals all errors; no condition values are returned. 


Arguments 


kb-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual keyboard identifier. The kb_id argument is the address of a 
longword that uniquely identifies a virtual keyboard. See UIS$CREATE_ 
KB for more information about the kb_id argument. 
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UIS$TEXT 

Draws a series of characters. 


Format 

UIS$TEXT vd—id, atb, text—string [,x,y] [,ctllist ,ctllen] 


Returns 

UIS$TEXT signals all errors; no condition values are returned. 


Arguments 


vd-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Virtual display identifier. The vd_id argument is the address of a Iongword 
that uniquely identifies a virtual display. See U1S$CREATE—DISPLAY for 
more information about the vd id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a Iongword 
integer that specifies an attribute block that modifies text output. When a 
control list is specified, the atb argument defines the initial attribute settings 
of the text string. 


text—String 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Text string. The text—string argument is the address of a character string 
descriptor of a text string. 
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XfY 

VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Starting point of text output. The x and y arguments are the addresses of 
f—floating point numbers that define in world coordinates of the starting 
point of text output. The starting point is the upper-left comer of the 
character cell of the next character to be drawn. 


If this argument is not specified, the current text position is used. (See the 
UIS$SET—ALIGNED—POSITION routine for more information.) 


When a control list is specified, the x,y arguments specify the starting 
coordinate for the first character of the character string. 


ctUist 


VMS Usage: 
type: 
access: 
mechanism: 


vector—longword—unsigned 
longword (unsigned) 
read only 
by reference 


Text formatting control list. The ctllist argument is the address of an 
array of longwords that define the font, text rendition, text formatting, and 
positioning of fragments of the text string. When a control list is specified, 
the atb argument defines the initial attribute settings of the text string 

If ctllist is not specified) text rendition and position are the values specified 
in the arguments atb and x,y. 

The control list consists of a sequence of data elements, each two longwords 
in length. The first longword of each element is a tag. The second longword 
is either a value particular to the type of element specified or zero. Following 
is a diagram showing the stmcture of a text control list. 
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UIS$C_TEXT_ATB 


Attribute Block Number 


UIS$C_TEXT_SAVEPOSITION 


0 


UIS$C_TEXT_IGNORE 


Command Value 


UIS$C_TEXT_END_OF_LIST 

ZK-5426-86 

The following table describes valid formatting commands. 


Formatting Command 

Function 

Commands Without Values^ 

UIS$C_TEXT_NOP 

UIS$C_TEXT_RESTORE-POSITION 

UIS$C_TEXT_SAVE-POSITION 

Nil operation 

Restores the current writing position 

Saves the current writing position 

Commands Requiring Values 

UIS$C-TEXT-ATB 

UIS$C-TEXT-HPOS-ABSOLUTE 

UIS$C-TEXT-HPOS-RELATIVE 

UIS$C-TEXT-IGNORE 

Specifies an attribute block number 
Specifies a new current x position 
Modifies the current x position by a delta 
Skips n characters 

^Second longword must be zero 
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Formatting Command 

Function 

Commands Requiring Values 


UIS$C_TEXT_NEW_LINE 

Skips n new lines and positions at the 
left margin 

UIS$C_TEXT_TAB_ABSOLUTE 

Writes white space to the new absolute 
position 

UIS$C_TEXT_TAB_RELATIVE 

Writes white space to the new relative 
position 

UIS$C_TEXT_VPOS_ABSOLUTE 

Writes a new current y position 

UIS$C_TEXT_VPOS_RELATIVE 

Modifies the current y position by a delta 

UIS$C_TEXT_WRITE 

Writes n characters 

Commands Not Requiring a Second Longword 

UIS$C_TEXT_END_OF_LIST 

Terminates the control list 


When UIS encounters illegal commands and values within the control list, it 
skips the invalid item and signals an error. 


ctllen 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Length of formatting control list. The ctllen argument is the address of a 
longword that specifies the length of the formatting control list in longwords. 


Description 

Nonprinting characters such as tab and line feed are not handled in any 
special way. The character is obtained from the font and is displayed like 
any other character. 
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UIS$TRANSFORM^OBJECT 

Transforms the coordinates or attributes or both of the specified object within 
the display list. 


Format 

UIS$TRANSFORM_OBJECT | °eg% } [.matrix] [,atb] 


Returns 

UlS$TRANSFORM_OBJECT signals all errors; no condition values are 
returned. 


Arguments 

obj^id 
VMS Usage; 
type: 
access: 
mechanism; 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Object identifier. The obj—id argument is the address of a Iongword that 
uniquely identifies the object. 


seg—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Segment identifier. The seg_id argument is the address of a Iongword that 
uniquely identifies the segment. See UIS$BEG1N_SEGMENT for more 
information about the seg_id argument. 

matrix 

VMS Usage; vector_iongword—signed 
type: F—fioating 

access: read oniy 

mechanism: by reference 


Transformation matrix. The matrix argument is the address of an array of 
Iongword integers that define the values to be used for scaling, rotation. 
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and/or translation. A two-dimensional array declared as ARRAY(2,3) has the 
following structure. 


1,1 

1,2 

1,3 

2,1 

2,2 

2,3 


ZK 5492-86 


VAX FORTRAN allocates memory for the array elements. Memory addresses 
of array elements range from lowest to highest in the following order: 
(1,1)/(2,1)/ (1/2),(2,2),(1,3), and (2,3)- UIS assigns values to array elements in 
the order shown in the following illustration. 

NOTE: For the purposes of assigning values to array elements, UIS treats 
all transformation matrices as VAX FORTRAN arrays regardless of the 
programming language of the application. 


1 

3 

5 

2 

4 

6 


ZK-5493-86 


Pairs of array elements govern how displayed objects are scaled, rotated, 
and translated. UIS computes the transformed coordinates in the following 
manner. 

Xj = A(l,l)*x + A(l,2)*y + A(l,3) 
yj = A(2,l)*x + A(2,2)*y + A(2,3) 


Translation 

When translation alone is performed, the following array elements are 
assigned values. Dx and Dy represent distances between the original 
coordinates and the new coordinates. 
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T' 

0 

Dx 

0 

1 

Dy 


ZK-5494-86 


Scaling 

When scaling alone is performed, the following array elements are assigned 
values. 


Sx 

0 

0 

0 

Sy 

0 


ZK'5495-86 


Rotation 

When rotation alone is performed, the following array elements are assigned 
values, where is the desired angle of rotation. The values returned from 
the FORTRAN SIN and COS functions are stored in the appropriate array 
elements. 


cos (@) 

sin (@) 

0 

-sin (@) 

cos (@) 

0 


ZK-5496-86 


An unlimited number of transformations can be performed at one time by 
simply multiplying the matrices together into a single matrix using matrix 
multiplication. 

In order to multiply two matrices together, you must add a row to the bottom 
of each matrix. 
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ZK-5461-86 


After the multiplication is performed, remove the last row of the result. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block to override current attribute settings. 


Description 

Either the coordinates can be transformed, or the attributes can be overridden 
or both. 

After a transformation, occluded objects may not appear correctly. This can 
be corrected by calling UIS$EXECUTE to refresh the display screen. 


Example 


REAL*4 MATRIX(2.3) 


CALL UIS$PLOT(VD_ID.0.5.0.5.0,15.0.5.0,10.0,15.0,5.0,5.0) 

CURRENT_ID=UIS$GET_CURRENT_OBJECT(VD_ID) 

0BJ_ID=CURRENT_ID 
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CALL UIS$SET_F0NT(VD.ID.0,1,’UIS$FILL_PATTERNS’) 

CALL UIS$SET_FILL_PATTERN(VD.ID.1.1.PATT$C_H0RIZ1_7) 

PAUSE 

MATRIX(1.1)=1.0 
MATRIX(2,1)=0.0 
MATRIX(1.2)=0.0 
MATRIX(2,2)=1.0 
MATRIX(1,3)=-10.0 
MATRIX(2.3)=-10.0 

CALL UIS$TRANSF0RM_0BJECT(OBJ.ID,MATRIX,1) 

PAUSE 

MATRIX(1.1)=2.0 
MATRIX(2,1)=0.0 
MATRIX(1.2)=0.0 
MATRIX(2,2)=2.0 
MATRIX(1,3)=0.0 
MATRIX(2,3)=0.0 

CALL UIS$TRANSFORM_OBJECT(OBJ.ID,MATRIX,1) 

PAUSE 

CALL UIS$SET.FONT(VD.ID.0.2.’UIS$FILL.PATTERNS’) 

CALL UIS$SET.FILL.PATTERN(VD.ID,2.2.PATT$C.VERT1.7) 

MATRIX(1,1)=1.0 
MATRIX(2.1)=0.0 
MATRIX(1.2)=0.0 
MATRIX(2.2)=1.0 
MATRIX(1.3)=-13.0 
MATRIX(2.3)=-13.0 

CALL UISSTRANSFORM.OBJECT(OBJ.ID,MATRIX.2) 
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PART IV UlS Device Coordinate (UlSDC) 
Routines 




Chapter 19 

UlS Device Coordinate Graphics Routines 


19.1 Overview 

This section introduces the Micro VMS workstation UISDC (device coordinate) 
graphics system services. It contains a reference section of all UISDC routines and 
pertinent information on how they are used. 


19.2 UISDC Routines—How to Use Them 

In addition to the world coordinate interface (UIS), the Micro VMS workstation 
software provides a device-coordinate, or pixel-level, interface (UISDC) to the 
graphics system services. UISDC allows applications to create UIS windows, but 
manipulate the contents of those windows at the pixel level. 

Programming in device coordinates requires that an application make mixed use 
of UIS and UISDC routines. Only those UIS routines that use or modify world 
coordinate positions have been duplicated as UISDC routines. Most informational, 
attribute, windowing, and display routines exist only in UIS format and are shared 
by the two programming levels. 

The major differences between UISDC and UIS are: 

• The UISDC drawing surface is a display window, as opposed to a virtual display 
as it is with UIS. Therefore, the UISDC output routines utilize display window 
identifiers instead of virtual display identifiers. 

• Most UISDC positions are expressed in viewport-relative device coordinates. 

The lower-left comer of the display viewport is pixel (0,0). The upper-right 
comer is (width multiplied by x resolution, height multiplied by y resolution), 
where width and height are expressed in centimeters and resolution is expressed 
in pixels per centimeter. 
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• UISDC does not maintain or manage a display list. Automatic zooming, panning, 
and playback of a display are not supported. 

Mixed use of UIS and UISDC output routines is allowed. Therefore, it is possible to 
do the following UIS and UISDC operations simultaneously: 

• Draw to a virtual display that contains a window, using world coordinates. 

• Draw directly to the same window, using viewport-relative device coordinates. 

Separate current text positions, character size, text margins, and clipping rectangles 
are maintained for both coordinate systems. 

The following section of this chapter lists the UISDC routines and their arguments in 
alphabetical order. 
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UISDC$ALLOCATE-DOP 

UISDC$ALLOCATE_DOP 

Allocates a drawing operation primitive (DOF) for a particular display 
window in VAXstation color and intensity systems. 

Format 

Gfop=UISDC$ALLOCATE_DOP wdUd ,size ,atb 

Returns 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as the address of the drawing operation primitive 
in the variable dop or RO (VAX MACRO). 

UISDC$ ALLOC ATE _DOP signals all errors; no condition values are 
returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

size 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Size of the variable portion of the drawing operation primitive. The size 
argument is the address of a number that defines the size of the variable 
portion of the drawing operation primitive to allocated. 





19-4 UlSDC Routines 

UISDC$ALLOCATE_DOP 


The size of the variable portion of the allocated DOP is returned in the size 
field. The size of the allocated DOP may be smaller than the requested size. 

atb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of an attribute 
block. 


Description 

UISDC$ ALLOC ATE—DOP writes the following information from the 
specified attribute block into portions of the DOP data structure and returns 
the address of the DOP. 

• Clipping rectangle 

• Writing mode 

• Writing mask 

See the MicroVMS Workstation Video Device Driver Manual for more 
information. 
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UISDC$CIRCLE 


UlSDCSCIRCLE 

Draws an arc along the circumference of a circle. 

Format 

UISDC$CIRCLE wd—id, atb, center—x, center—y, xradius 
[, start—deg, end—deg] 

Returns 

UISDC$CIRCLE signals all errors; no condition values are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 

atb 

VMS Usage: Iongword—unsigned 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a Iongword 
integer that specifies an attribute block that^ontrols the appearance of the 
circle or arc. 

center—X, center—y 
VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Center position x and y viewport-relative device coordinates. The center— x 
and center—y arguments are the addresses of integers that define a point in 
the virtual display that is the center of the arc or circle. 
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xradius 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Radius of the circle specified as an x viewport-relative device coordinate 
width. The xradius argument is the address of an integer that defines the 
distance from the center of the circle to the circumference of the circle. 


Start—deg, end—deg 


VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
f—floating 
read only 
by reference 


Degree at which the arc starts. The start—deg and end—deg arguments 
are the addresses of f—floating numbers that define the starting and ending 
point on the circumference of the circle where the arc or circle will be 
drawn. Degrees are measured clockwise from the top of the circle. If these 
arguments are not specified, 0.0 degrees and 360.0 degrees are assumed, 
respectively. 


Description 

UISDC$CIRCLE draws an arc specified by a center position and a radius for 
the range of the degrees specified. 

The arc is closed by drawing one or more lines between the endpoints. The 
arc type associated with the attribute block specifies the way in which the arc 
is closed. The arc is not closed off by default. See UIS$SET—ARC—TYPE for 
details. 

The points are drawn with the current line pattern and width, and filled with 
the current fill pattern, if enabled. 

UISPC$CIRCLE does not support the following combination of attributes: 

• Line width not equal to 1 and line style not equal to FFFFFFFFj^ 

• Line width not equal to 1 and complement writing mode 

Circles are distorted by virtual display/display window aspect ratio 
distortion. 




UlSDC Routines i9-7 
UISDC$ELLIPSE 


UISDC$ELLIPSE 

Draws an arc at a starting position along the circumference of an ellipse. 

Format 

UISDC$ELLIPSE wd—id, atb, center—x, center—y, xradius, 
yradius [, start—deg ,end-deg] 

Returns 

UISDC$ELLIPSE signals all errors; no condition values are returned. 

Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Virtual display identifier. The wd_id argument is the address of a Iongword 
that uniquely identifies the virtual display. See UIS$CREATE_DISPLAY for 
more information about the wd_id argument. 

atb 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Attribute block number. The atb argument is the address of a Iongword that 
identifies the attribute block that will modify the ellipse. If you specify 0 in 
the atb argument, the default settings of attribute block 0 are used. 

center—X, center—y 
VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Center position x and y viewport-relative device coordinates. The center_x 
and center_y arguments are the addresses of integers that define a point in 
the display window that is the center of the ellipse or arc. 
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xradius 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Radius of the ellipse specified as an x device coordinate width. The xradius 
argument is the address of an integer that defines the distance from the 
center of the ellipse to the circumference of the ellipse or arc. 


yradius 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Radius of the ellipse specified as a y device coordinate width. The yradius 
argument is the address of a integer that defines the distance from the center 
of the ellipse to the circumference of the ellipse or arc. 


start^deg, end^deg 
VMS Usage: floating-point 
type: f-floating 

access: read only 

mechanism: by reference 


Degree at which the arc starts and ends. The start _deg and end_deg 
arguments are the addresses of f_floating numbers that define the starting 
point and ending point in degrees on the circumference of the ellipse where 
the arc or ellipse will be drawn. Degrees are measured clockwise from the 
top of the ellipse. 

If these arguments are not specified, 0.0 and 360.0 degrees are assumed. If 
both arguments are not specified, a complete ellipse is drawn. 


Description 

UISDC$ELLIPSE uses center position coordinates and x and y radii to 
construct an ellipse. Along the circumference of this ellipse, UISDC$ELLIPSE 
draws an arc for a specified range of degrees. 

The arc is closed by drawing one or more lines between the endpoints. The 
type of arc associated with the attribute block specifies the way in which the 
arc is closed. See the UIS$SET_ARC_TYPE routine for more information. 

The points are drawn with the current line pattern and width, and filled with 
the current fill pattern, if enabled. 
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UISDC$ELLIPSE 

UISDC$ELLIPSE does not create thick patterned ellipses and thick ellipses 
that are undefined in complement mode. 

UISDC$ELLIPSE does not support the following combination of attributes: 

• Line width not equal to 1 and line style not equal to FFFFFFFFk^ 

• Line width not equal to 1 and complement writing mode 
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UISDC$ERASE 

Erases the specified rectangle in the display window. 

Format 

UISDC$ERASE wd—id [,Xp yp 
Returns 

UISDC$ERASE signals all errors; no condition values are returned. 


Arguments 

wd-id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window containing the 
specified rectangle. See UIS$CREATE_WINDOW for more information 
about the wd_id argument. 

Xp Yp X2, Yz 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Viewport-relative device coordinate pairs. The and yj arguments are the 
addresses of integers that define the lower-left corner of the rectangle in the 
display window. The X 2 and y 2 arguments are the addresses of integers that 
define the upper-right corner of the rectangle in the display window. If no 
rectangle is specified, the entire display window is erased. 

Description 

Areas within display windows affected by this call are filled with the color 
specified by entry 0 in the virtual display color map. 
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UISDC$EXECUTEJOP-J^SYNCH 

Starts the execution of the specified drawing operation primitive (DOP) in 
the specified display window of VAXstation color and intensity systems and 
returns control to the application immediately. 


Format 

UISDC$EXECUTE_DOP_ASYNCH wd-id ,dop Josb 


Returns 

UISDC$EXECUTE_DOP—ASYNCH signals all errors; no condition values 
are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


dop 

VMS Usage: 
type: 
access: 
mechanism: 


vector_byte—unsigned 
byte—unsigned 
read only 
by reference 


Drawing operation primitive. The dop argument is the address of an array of 
bytes that comprise the drawing operation primitive. 


iosb 


VMS Usage: 
type: 
access: 
mechanism: 


io—status—block 
quadword (unsigned) 
write only 
by reference 
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I/O status block. The iosb argument is the address of an I/O status block 
that receives a value indicating that the drawing operation primitive is 
queued for execution. 


Description 

UISDC$EXECUTE_DOP_ASYNCH queues the specified DOP for execution 
in the specified window. 

You may later use the SYS$SYNCH system service to determine when the 
DOP has been drawn. See the MicroVMS Workstation Video Device Driver 
Manual for more details. 
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UISDC$EXECUTE^DOR_SYNCH 

Queues the drawing operation primitive (DOP), waits for the specified DOP 
to complete execution in the specified display window, and then returns 
control to the application. 


Format 

UISDC$EXECUTE_DOP_SYNCH wd-id ,dop 


Returns 

UISDC$EXECUTE_DOP_SYNCH signals all errors; no condition values are 
returned. 


Arguments 


wd-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 


dop 

VMS Usage: 
type: 
access: 
mechanism: 


vector—byte_unsigned 
byte—unsigned 
read only 
by reference 


Drawing operation primitive. The dop argument is the address of an array of 
bytes that comprises the drawing operation primitive. 


Description 

UISDC$EXECUTE—DOP—SYNCH queues the specified drawing operation 
primitive for execution in the specified window and returns when the 
drawing operation is complete. 

See MicroVMS Workstation Video Device Driver Manual for more information. 
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UISDC$GET-ALIQNED_POSITION 

UISDC$GET_ALIGNED_POSITION 

Returns the current position for text output—the upper-left comer of the next 
character cell. 

Format 

UISDC$GET-JVLIGNED_POSITION wd-id, atb, retx, rety 
Returns 

UISDC$GET_ALIGNED_POSITION signals all errors; no condition values 
are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 

atb 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Attribute block. The atb argument is the address of a Iongword that identifies 
an attribute block that contains a modified font attribute. 

retx, rety 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: write oniy 

mechanism: by reference 

Viewport-relative device coordinate pair. The retx and rety arguments are 
the addresses of longwords that receive the current position as x and y 
viewport-relative device coordinate positions. 
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Description 

UISDC$GET_ALIGNED_POSITION differs from UISDC$GET_POSITION 
in that the current position refers to the upper-left comer of the next 
character to be output using the specified attribute block. This is useful 
for applications that require the position of the upper-left comer, but do not 
have enough information about the font baseline to determine the proper 
alignment point. The position is converted into the proper alignment point 
using the font specified in the given attribute block. See UISDC$SET_ 
ALIGNED-POSITION. 
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UISDC$GET_CHAR^SIZE 

Returns both a value indicating whether or not character scaling is enabled 
and the character size used. 


Format 

iboo/eaA7=UISDC$GET_CHAR_SIZE wd-id, atb 

,[char],[width][,height] 


Returns 


VMS Usage; 
type: 
access; 
mechanism: 


boolean 

longword (unsigned) 
write only 
by value 


Longword value returned as a Boolean to indicate the status of character 
scaling in the variable boolean or RO (VAX MACRO). 

UISDC$GET_CHAR_S1ZE signals all errors; no condition values are 
returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd__id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block containing the character size attribute setting. 
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char 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character_string 
write only 
by descriptor 


Single character. The char argument is the address of a character string 
descriptor of a single char. 


width 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Character width. The width argument is the address of a longword that 
receives the character width in viewport-relative device coordinates. 


height 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Character height. The height argument is the address of a longword that 
receives the character height in viewport-relative device coordinates. 
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UISDC$GET_CLIP 


Returns the clipping mode. 


Format 

sfaft;s=UISDC$GET_CLIP wd—id, atb [,Xp yp x^, 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


boolean 

longword (unsigned) 
write only 
by value 


Boolean value returned as the clipping mode in a status variable or RO (VAX 
MACRO). If clipping is enabled, a Boolean TRUE is returned. If clipping is 
disabled, a Boolean FALSE is returned. 


UISDC$GET_CLIP signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies the attribute block that modifies the clipping mode. 
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^1, y\, X2, y2 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Viewport-relative device coordinate pairs. The Xj and arguments are the 
addresses of longwords that receive the viewport-relative device coordinates 
of the lower-left comer of the clipping rectangle. The X 2 and y 2 arguments 
are the addresses of longwords that receive the viewport-relative device 
coordinates of the upper-right comer of the clipping rectangle. 
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UISDC$GET__POINTER_POSITION 

Returns the current pointer position in viewport-relative device coordinates. 


Format 

sfati/s=UISDC$GET JOINTER_POSITION wdUd, retx, rety 
Returns 

VMS Usage: boolean 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Boolean value returned as the current position of the pointer in a status 
variable. UISDC$GET_POINTER-POSITION returns the Boolean TRUE 
value 1 if the pointer is within the visible portion of the viewport, 0 is 
returned if the pointer is outside the visible portion of the viewport. In the 
latter case, the x and y values are returned as 0,0. 

UISDC$GET_POINTER—POSITION signals all errors; no condition values 
are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE— 
WINDOW for more information about the wd_id argument. 

retx, rety 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Viewport-relative device coordinate pair. The retx and rety arguments are 
the addresses of longwords that receive the pointer position in viewport- 
relative device coordinates. 
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Description 

Note that the returned status value should always be tested when using 
this routine, since it is always possible that the pointer could be outside the 
window when the service is called and the x,y values would be meaningless. 
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UISDC$GET^POSITION 


Returns the current baseline position for text output. 


Format 

UISDC$GET_POSITION wd-id, retx, rety 


Returns 

UISDC$GET_POSITION signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage; 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


retx, rety 

VMS Usage: 
type; 
access: 
mechanism: 


iongword—unsigned 
longword (unsigned) 
write only 
by reference 


Viewport-relative device-coordinate pair. The retx and rety arguments are 
addresses of longwords that receive the current position of text output in 
viewport-relative device coordinate positions. 


Description 

UIS$NEW_TEXT_LINE and UIS$TEXT recognize the concept of current 
position. The position refers to the alignment point on the baseline of the 
next character to be output. (See the UIS$SET_JPOSITION routine.) 
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UISDC$GET_TEXT_MARGINS 

Returns the text margins for a line of text. See UISDC$SET_TEXT_ 
MARGINS for more information. 


Format 

UISDC$GET_TEXT_MARGINS wd-id ,atb ,x ,y 

[, margin—length] 


Returns 

UISDC$GET_TEXT_MARGINS signals all errors; no condition values are 
returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Virtual display identifier. The wd_Jd argument is the address of a longword 
that uniquely identifies the virtual display. See UIS$CREATE—WINDOW for 
more information about the wd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block. 


x,y 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 







19-24 UlSDC Routines 

UISDC$GET-TEXT_MARGINS 


Starting margin position. The x,y arguments are the addresses of longwords 
that receive the starting margin relative to the direction of text drawing in 
viewport-relative device coordinates. 

margin—length 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Ending margin position. The margin_length is the address of a longword 
that receives the distance to the end margin in viewport-relative device 
coordinates. The margin is measured along the actual path of text drawing. 
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UISDC$GET_VISIBILITY 

Returns a Boolean value that indicates whether or not the specified rectangle 
in the display window is visible. 


Format 

Soo/ear7=UISDC$GET_VISIBILITY wd-id ix^, [,X 2 , y 2 ]] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


boolean 

longword (unsigned) 
write only 
by value 


Boolean value returned in a status variable or RO (VAX MACRO). The 
returned value, the visibility status, is a Boolean TRUE only if the entire area 
is visible, and a Boolean FALSE if even a portion of the area is occluded or 
clipped. 

UISDC$GET_VISIBILITY signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd__id argument is the address of a 
longword that uniquely identifies a display window. See UIS$ CREATE— 
WINDOW for more information about the wd—id argument. 


Xi, Yv X2, Yi 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinates of a rectangle in the display window. 
The Xj and yj arguments are addresses of integers that define the lower-left 
comer of a rectangle in the display window. The X 2 and ji arguments are 
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addresses of integers that define the upper-right corner of a rectangle in the 
display window. 

If the coordinates of the rectangle are not specified, the dimensions of the 
entire display window are used by default. 


Description 

UIS$GET_VISIBIL1TY determines if a single position is visible by specifying 
the same coordinate for both minimum and maximum values. 
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UISDC$IMAGE 

Draws a raster image into a specified display rectangle. 

Format 

UISDC$IMAGE wd—id, atb, Xp yp x^, rasterwidth, 
rasterheight, bitsperpixel, rasteraddr 

Returns 

UISDC$IMAGE signals all errors; no condition values are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

atb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block that modifies the writing mode. 

Xp Yp X2, 72 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinates of the rectangle in the display window. 
The Xj and arguments are the addresses of integers that define the lower- 
left comer of the rectangle in the display window. The X 2 and 72 arguments 
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are the addresses of integer pixels that define the upper-right corner of the 
rectangle in the display window. 


rasterwidth 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Width of the raster image. The rasterwidth argument is the address of a 
longword that defines the width of the raster image in pixels. 

rasterheight 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 


Height of the raster image. The rasterheight is the address of a longword 
that defines the height of the raster image in pixels. 


bitsperpixel 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Number of bits per pixel in the raster image. The bitsperpixel argument is 
the address of a longword that defines the number of bits per pixel in the 
raster image. The bitsperpixel argument is currently required to be either 1 
or 8. 


If bitsperpixel is specified as 8 on a single-plane system, the results are 
unpredictable. 

rasteraddr 

VMS Usage: vector—longword—unsigned 
type: longword—unsigned 

access: read only 

mechanism: by reference 

Raster image. The rasteraddr argument is the address of an array that 
defines a raster image. 
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Description 

The raster dimensions are described by the width, height, and bits per 
pixel parameters. The width and height give the number of pixels in each 
dimension, and bits per pixel represents the number of bits that makes up 
each pixel. The raster is read from memory as "height" bit vectors each of 
which is "width" pixels long and each pixel is "bits/pixel" bits long. 

U1SDC$IMAGE never scales. If the size of the destination rectangle is larger 
than the size of the raster, then the remaining space on the right and top will 
not be written. 

The procedure for assignment of bits in the bitmap is as follows: 

1. Each bit in the array is set from left-most bit to the right-most bit 

2. Each row is filled from the top row to the bottom row. 

NOTE: The bitmap is not byte- or word-aligned. 

The following figure illustrates the setting of bits in the bitmap. 
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UISDC$LINE 

Draws a line or series of unconnected lines. 


Format 

UISDC$LINE wd-id, atb, x,, y, ^.x^.y^ [,...x„,yn]] 


Returns 

UISDC$LINE signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a Iongword 
integer that identifies an attribute block that modifies line style and line 
width or both. 


x,y 

VMS Usage: 
type: 
access: 
mechanism: 


Iongword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Viewport-relative device coordinate pair. The x and y arguments are the 
addresses of integers that define a point in the display window. 

If the arguments are repeated to specify a second position, a line is created. 
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If one coordinate pair is specified, a point is drawn. If any other odd number 
of coordinate pairs is specified, the final coordinate pair is ignored. 

Up to 126 world coordinate pairs may be specified as arguments. See the 
"DESCRIPTION" section below for more information about this argument. 


Description 

If one position is specified, then a point is drawn. If two positions are 
specified, a single vector is drawn. 

Up to 252 arguments can be specified, that is, 63 unconnected lines may 
be drawn. If a larger number of points must be specified in a single call, 
UIS$LINE_ARRAY should be used. 

The points or lines are drawn with the line pattern and width for the attribute 
block. Fill pattern attribute settings are ignored. 
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UISDCSLINE-ARRAY 

Draws an unfilled point, line, or a series of unconnected lines depending on 
the number of positions specified. 


Format 

UISDC$LtNE^RRAY wd—id, atb, count, X—vector, y—vector 


Returns 

UISDC$LINE—ARRAY signals all errors; no condition values are returned. 


Arguments 


yudLJd 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifie' a display window. See U1S$CREATE_ 
WINDOW for more information about the wd—id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword 
integer that identifies an attribute block that modifies line style or line width 
or both. 


count 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
iongword (unsigned) 
read only 
by reference 


Number of points. The count argument is the address of longword integer 
that denotes the number of viewport-relative device coordinate pairs defined 
in the arguments X—vector and y— vector. 
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X—vector, y—vector 

VMS Usage: vector.longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Array of x and y viewport-relative device coordinates. The x—vector and 
y_vector arguments are the addresses of arrays of integers whose elements 
together define in viewport-relative device coordinates the starting and end 
points of lines drawn in the display window. 


Description 

U1SDC$LINE—ARRAY performs the same functions as UISDC$LINE except 
that X and y coordinates are stored in arrays. 

A maximum of 31,767 points can be plotted in a single call. UISDC$LINE_ 
ARRAY is the same as UISDC$LINE except that the x and y coordinates are 
specified using two arrays, each of length count points. 
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UISDC$LOAD_BITMAP 

Loads a bitmap into offscreen memory on VAXstation color and intensity 
systems. 

Format 

bitmap—id ^U\SDC$LO AD—BITMAP wd—id,bitmap—adr 

, bitmap—len 
, bitmap—width 
,bits—per—pixel 

Returns 

VMS Usage: identifier 
type: iongword (unsigned) 

access: write oniy 

mechanism: by vaiue 

Longword value returned as the bitmap identifier in the variable bitmap—id 
or RO (VAX MACRO) for use in DOP$L _BITMAP_ID field of a drawing 
operation primitive (DOP). 

UISDC$LOAD_BITMAP signals all errors; no condition values are returned. 

Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See 
UIS$CREATE—WINDOW for more mformation about the wd_id. 

bitmap—adr 

VMS Usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

Bitmap address. The bitmap—adr argument is the address of a bitmap. 
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bitmap—len 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
iongword (unsigned) 
read only 
by reference 


Bitmap length. The bitmapJen argument is the address of the number that 
defines the length of the bitmap in bytes. The length must be a multiple 
of 2. 


bitmap—width 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Width of the bitmap. The bitmap_width argument is the address of a 
number that defines the width of the bitmap in pixels. If the number of bits 
per pixel is 1, the specified width must be a multiple of 16. 


If the width of the bitmap should not exceed 1024. 


bits—per—pixei 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


The bits—per—pixel argument is the address of a number that defines the 
number of bits per pixel. Currently, the values 1 and 8 are supported. 


Description 

See the MicroVMS Workstation Video Device Driver Manual for more 
information. 
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UISDC$MEASURE_TEXT 

Measures a text string as if it were output in a display window. 

Format 

UISDC$MEASURE_TEXT wd—id, atb, text—string, retwidth, 

retheight, [,ctllist, ctUen] Iposarray] 

Returns 

UISDC$MEASURE_TEXT signals all errors; no condition values are 
returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

atb 

VMS Usage: iongword—unsigned 
type: iongword (unsigned) 

access: read oniy 

mechanism: by reference 

Attribute block number. The atb argument is the address of a Iongword that 
identifies an attribute block that modifies text output. 

text—string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text string. The text—String argument is the address of a character string 
descriptor of a text string. 
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retwidth,retheight 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Dimensions of the text string. The retwidth and retheight arguments are 
the addresses of longwords that receive the width and height of the text in 
centimeters. 


ctllist 


VMS Usage: 
type: 
access: 
mechanism: 


vector_longword—unsigned 
longword (unsigned) 
read only 
by reference 


Text formatting list. The ctllist argument is the address of an array of 
longwords that describes the font, text rendition, format, and positioning 
of text string fragments. See UIS$TEXT for a complete description of the • 
formatting control list. 


ctllen 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Length of the text formatting control list. The ctllen argument is the address 
of a longword that defines the length of the text formatting control list. 


posarray 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword_unsigned 
longword (unsigned) 
write only 
by reference 


Character position array. The posarray argument is the address of an 
array of longwords that receives character positions in pixels that are 
relative offsets at which each character would have been displayed. See 
UIS$MEASURE_TEXT for a complete description of the character position 
array. 


Description 

UISDC$MEASURE_TEXT is used in justification and text positioning 
applications. The routine returns the height and width of the text string 
in viewport-relative device coordinates. 
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UISDC$MOVE_AREA 

Shifts a portion of a display window to another position in the window. 

Format 

UISDC$MOVE_AREA wd—id, Xp yp y^, new^, new—y 

Returns 

UISDC$MOVE_AREA signals all errors; no condition values are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

Xp yp X2, y2 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinates of the source rectangle. The Xj and y^ 
arguments are the addresses of integers that define the lower-left comer of 
the source rectangle. The X 2 and 72 are the addresses of integers that define 
the upper-right comer of the source rectangle. 

new—x, new—y 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinate pair. The new— x and new— y arguments 
are the addresses of integers that define the lower-left comer of the 
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destination rectangle. The height and width of the destination rectangle 
is implied from the height and width of the source rectangle. 


Description 

Note that display objects that are only partially contained within the specified 
source rectangle, though partially moved within existing display windows 
will be completely moved within the display list. 

The nonoccluding portion of the source rectangle (if any) is erased after the 
operation. 
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UISDC$NEW__TEXT_LINE 

Moves the current text position along the actual path of text drawing to the 
starting margin and then along the margin in the direction of the minor text 
path. Depending on the minor text path, either the width or height of the 
character cell is used for spacing between characters and lines. 


Format 

UISDC$NEW_TEXT_LINE wd-id, atb 


Returns 

U1SDC$NEW_TEXT_LINE signals all errors; no condition values are 
returned. 


Arguments 


wd^id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block. 
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UISDC$PLOT 

Draws a filled or unfilled point, line, or polygon depending on the number of 
positions specified. 


Format 

UISDC$PLOT wd-id, atb, Xp y, [,X2,y2 [,...Xn,yn]] 


Returns 

UISDC$PLOT signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See U1S$CREATE_ 
WINDOW for more information about the wd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
identifies an attribute block that modifies line style and line width. 


x,y 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Viewport-relative device coordinate pair. The x and y arguments are the 
addresses of integers that define a point in the display window. If the 
argument be used to specify a second position, a line is created. Up to 126 
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viewport-relative device coordinate pairs may be specified as arguments. See 
the DESCRIPTION section below for more information about this argument. 


Description 

If one position is specified, then a point is drawn. If two positions are 
specified, a single vector is drawn. If more than two positions are specified, 
a connected polygon is drawn. Up to 252 arguments can be specified, giving 
a maximum of a 126-point polygon using this routine. If a larger number of 
points must be specified in a single call, UISDC$PLOT_ARRAY should be 
used. 

The points or lines are drawn with the line pattern and width for the attribute 
block, and if FILL is enabled for the attribute block, the enclosed area is filled 
with the current fill pattern. 

NOTE: VAX PASCAL application programs that draw lines and polygons 
should use UISDC$PLOT_ARRAY. 




19-44 UlSDC Routines 

UISDC$PLOT_ARRAY 


UISDC$PLOT_ARRAY 

Draws an unfilled or filled point, line or polygon depending on the 
number of positions specified. This routine performs the same functions 
as UISDC$PLOT. 


Format 

UISDC$PLOT_ARRAY wd—id, atb, count, X—vector, y^vector 


Returns 

UISDC$PLOT_ARRAY signals all errors; no condition values are returned* 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a Iongword that 
identifies an attribute block that modifies line style or line width or both. 


count 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
Iongword (unsigned) 
read only 
by reference 


Number of points. The count argument is the address of Iongword that 
denotes the number of viewport-relative device coordinate pairs defined in 
the X —vector and y— vector arguments. 
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X—vector, y—vector 
VMS Usage: vector_longword—signed 
type: longword—signed 

access: read only 

mechanism: by reference 

Array of x and y viewport-relative device coordinates. The x_vector 
argument is the address of an array of integers whose elements are the x 
viewport-relative device coordinate values of points defined in the window 
display. The y_vector argument is the address of an array of integers whose 
elements are the y viewport-relative device coordinate values of points 
defined in the display window. 


Description 

A maximum of 65,535 points can be plotted in a single call. 
UISDC$PLOT_ARRAY is the same as UISDC$PLOT except that the x and y 
viewport-relative device coordinates are specified using two arrays, each of 
length n points. 
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UISDC$QUEUE_DOP 

Queues the specified drawing operation primitive (DOP) for execution in the 
specified window and then returns control to the application. 


Format 

UISDC$QUEUE_DOP wd-id ,dop 


Returns 

UISDC$QUEUE_DOP signals all errors; no condition values are returned. 


Arguments 


wd-id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd—id argument is the address of a 
Iongword that uniquely identifies the display window. See U1S$CREATE_ 
WINDOW for more information about the wd_id argument. 


dop 

VMS Usage: vector.byte.unsigned 
type: byte_usigned 

access: read only 

mechanism: by reference 


Drawing operation primitive. The dop argument is the address of an array of 
bytes that contains the drawing operation primitive. 


Description 

UISDC$EXECUTE_DOP_ASYNCH queues the specified drawing operation 
primitive (DOP) for execution in the specified-window. To obtain notification 
that the DOP has completed execution, see UISDC$EXECUTE_DOP_ 
ASYNCH and UISDC$EXECUTE_DOP_SYNCH. See the MicroVMS 
Workstation Video Device Driver Manual for more information about DOPs. 
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Reads a raster image from within a specified rectangle contained by a display 
window. 

Format 

UISDC$READ_IMAGE wd—id, Xp yp x^, I'ssterwidth, 

rasterheight, bitsperpixel, 

[rasteraddr], rasterlen 

Returns 

UISDC$READ_IMAGE signals all errors; no condition values are returned. 

Arguments 

wd—id 

VMS Usage: object—id 
type: longword 

access: read only 

mechanism: by reference 

Display window identifier. The wd—id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE— 
WINDOW for more information about the wd—id argument. 

xi,yi 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinates of lower-left comer of the specified 
rectangle. The Xpy\ arguments are the addresses of integers that define the 
lower-left comer of the rectangle in the display window. 

X2,y2 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 
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Viewport-relative device coordinates of the upper-right comer of the 
rectangle. The arguments are the addresses of integers that define 
the upper-right comer of the specified rectangle in the display window, 

rasterwidth 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Width of the raster image in pixels. The rasterwidth argument is the address 
of a longword that receives the width of the raster image in pixels. 

rasterheight 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Height of the raster image in pixels. The rasterheight argument is the 
address of a longword that receives the height of the raster image in pixels. 

bitsperpixe! 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Number of bits per pixel in the raster image. The bitsperpixel argument is 
the address of a longword that receives the number of bits per pixel in the 
raster image. 

rasteraddr 

VMS Usage: vector_byte—unsigned 
type: byte 

access: write only 

mechanism: by reference 

Address of buffer in which to return the raster image. The rasteraddr 
argument is the address of an array of bytes that receives the raster image. 

rasterien 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Size in bytes of the buffer. The rasterien argument is the address of a 
longword that specifies the size in bytes of the buffer. 
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Description 

The raster image contained within the rectangle described by Xj, yj and X 2 , 
y 2 is returned in the specified buffer. The actual dimensions, in pixels, of 
the returned buffer is written to rasterwidth and rasterheight. The number 
of bits per pixel is written to bitsperpixel. If the size of the buffer specified 
by rasterlen is not large enough to accept the entire bitmap raster, then 
rasterwidth, rasterheight, and bitsperpixel are returned as 0 and no data is 
written to the buffer. 

If the buffer length is specified as 0, values are returned in rasterwidth, 
rasterheight, and bitsperpixel. These values can be used to calculate the 
size of the buffer needed to contain the raster image. 

You should specify a buffer length of 0 to obtain the width, height, and bits 
per pixels. Use these returned values to do the following: 

1. Calculate the correct buffer size 

2. Reissue the call with the correct data 
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UISDC$SET_J^LIGNED-POSITION 

Sets the current position for text output. This routine differs from 
UISDC$SET_POSITION in that the position refers to the upper-left comer of 
the next character to the output. 


Format 

UISDC$SET_ALIGNED_POSITION wd-id, atb, x, y 


Returns 

UISDC$SET_ALIGNED_POSITION signals all errors; no condition values 
are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb is the address of a longword that identifies 
an attribute block that contains the appropriate font attribute text attribute 
setting. 


x,y 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 
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Viewport-relative device coordinate pair. The x and y arguments are the 
addresses of integers that define the current position for text output. 


Description 

UISDC$SET_ALIGNED_POSITION is useful in applications that know the 
position of the upper-left comer, but also don't know enough about the font 
baseline to determine the proper alignment point. The position is converted 
into the proper alignment point using the font specified in the given attribute 
block. The alignment point is stored internally. 
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UISDC$SET_BUTTON_AST 

Allows an application to find out when a button on the pointing device is 
depressed or released in a given rectangle of the display window. 


Format 

UISDC$SET_BUTTON_AST wd-id [,astadr, [astprm] ,keybuf] 

[.Xp yp Ysl 


Returns 

UISDC$SET_BUTTON__AST signals all errors; no condition values are 
returned. 


Arguments 


wd—id 


VMS Usage; 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


astadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
read only 
by reference 


AST routine. The astadr argument is the address of an entry mask to a 
procedure that is called at AST level whenever a pointer button is depressed 
or released. To cancel the AST-enabling request of UISDC$SET_BUTTON_ 
AST, specify 0 in the astadr argument. To disable UIS$SET_BUTTON_AST, 
omit the astadr argument. 
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astprm 

VMS Usage: 
type: 
access: 
mechanism: 


user_arg 

longword (unsigned) 
read only 
by reference 


AST parameter. The astprm argument is the address of a single argument or 
data structure, such as a record or an array, to be passed to the AST routine. 
Calls to UlSDC$SET_BUTTON_AST in FORTRAN application programs 
should be coded as follows: %REF(%LOC(astprm)). 


keybuf 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
write only 
by reference 


Key buffer. The keybuf argument is the address of a longword buffer 
that receives button information whenever a pointer button is depressed 
or released. The low two bytes are the key code. The buttons are located 
on the left, center and right of the pointing device and are defined as 
UIS$C_POINTER_BUTTON_l, U1S$C_P01NTER_BUTT0N_2, UIS$C_ 
P01NTER_BUTT0N_3, and UIS$C-P01NTER_BUTT0N_4 respectively. 
The bit <31 > is set to 1 if the button has been pressed, and 0 if the button 
has been released. The buffer is not overwritten with subsequent button 
transitions until the AST routine completes. 


y\, X 2 , 72 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Viewport-relative device coordinates of a rectangle in the display window. 
The Xi and yj arguments are the addresses of integers that define the lower- 
left comer of a rectangle in the display window. The X 2 and y 2 arguments 
are the addresses of integer pixels that define the upper-right comer of a 
rectangle in the display window. 

If no rectangle is specified, the entire display window is assumed. 


Description 

This function can be called any number of times for different rectangles 
within the same display window or many display windows. 

See the DESCRIPTION section of UIS$SET_BUTTON—AST for information 
about pointer region priorities. 
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UISDC$SET^CHAR^SIZE 

Sets the viewport-relative device coordinate size of the specified character. 

Format 

UISDC$SET_CHAR_SIZE wd-id, iatb, oatb, [char], 

[width]], height] 

Returns 

UISDC$SET_CHAR_SIZE signals all errors; no condition values are 
returned. 


Arguments 

wd-id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window. See U1S$CREATE_ 
WINDOW for more information about the wd_id argument. 

iatb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
Iongword that identifies an attribute block to be modified. 

oatb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
Iongword that identifies a modified attribute block. 
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char 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Single character. The char argument is the address of a descriptor of a single 
character. You may specify any character in the font. Specify this argument 
when you are using proportionally spaced fonts to establish spacing and 
scaling factors among character within the font. The char has no effect on 
monospaced fonts. 

If char is not specified or if the specified character is invalid, the widest 
character in the font is chosen. 


width 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Character width. The width argument is the address of an integer that 
defines the character width in viewport-relative device coordinates. 


height 
VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Character height. The height argument is the address of an integer that 
defines the character height in viewport-relative device coordinates. 


Description 

To disable character scaling, omit all of the following arguments: char, 
width, and height. 

To scale characters to their nominal size as specified in the font, do not 
specify width or height. Scaling is only visible when you use a window that 
does not have same proportions as the virtual display. 

If you specify either width or height only, characters are scaled to the size 
you specify and in the direction you specify. In the unspecified direction, 
characters are scaled so as to maintain the same ratio of height and width as 
the unsealed character. 
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UISDC$SET^CLIP 

Sets a clipping rectangle within the display window. 

Format 

UISDC$SET_CLIP wd—id, iatb, oatb [,Xp 

Returns 

UISDC$SET_CLIP signals all errors; no condition values are returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd—id argument. 

iatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
longword value that identifies an attribute block to be modified. Either 
the attribute block 0 or a previously modified attribute block can be specified. 

oatb 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
longword value that identifies a newly modified attribute block that controls 
the dimensions of the clipping rectangle. 
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Xi, Yi, X2, y2 
VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
longword (unsigned) 
read only 
by reference 


Viewport-relative device coordinates of the clipping rectangle. The Xj and 
arguments are the addresses of integers that define the lower-left comer of 
the clipping rectangle in viewport-relative device coordinates. The Xi and y 2 
arguments are the addresses of integers that define the upper-right comer of 
the clipping rectangle in viewport-relative device coordinates. Only graphic 
objects and portions of graphic objects drawn within the clipping rectangle 
are seen. 


If the device coordinates of the clipping rectangle comers are not specified, 
then clipping is disabled for this attribute block. 



19-58 UlSDC Routines 

UISDC$SET_POINTER_AST 

UISDC$SET_POINTER_-AST 

Allows an application to find out when the pointer is moved in a given 
rectangle of the display window. 

Format 

UISDC$SET_POINTER_AST wd-id [,astadr [,astprm]] 

Yp y2] lexitastadr 

[,exitastprm]] 

Returns 

UISDC$SET_P01NTER_AST signals all errors; no condition values are 
returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read oniy 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See U1S$CREATE_ 
WINDOW for more information about the wd_id argument. 

astadr 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: read oniy 

mechanism: by reference 

AST routine. The astadr argument is the address of the entry mask to a 
procedure that is called at AST level whenever the pointer is moved within a 
rectangle in the display window. 

To cancel the AST-enabling request of UISDC$SET_P01NTER_AST for this 
argument only, specify 0 in the astadr argument and the coordinates of the 
rectangle. 
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astprm 

VMS Usage: 
type: 
access: 
mechanism: 


user_arg 

longword (unsigned) 
read only 
by reference 


AST parameter. The astprm argument is the address of a single argument or 
data structure, such as an array or record, passed to the AST routine. Calls 
to UISDC$SET_P01NTER_AST in VAX FORTRAN application programs 
should be coded as follows: %REF(%LOC(astprm)). 


Yv Yi 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Viewport-relative device coordinates of the rectangle of the display window. 
The Xj and yj arguments are the addresses of integers that define the lower- 
left comer of the rectangle of the display window. The X 2 and y 2 arguments 
are the addresses of integer pixels that define the upper-right corner of the 
rectangle of the display window. 

If no rectangle is specified, the entire display window is assumed. 

To cancel an AST-enabling request, specify 0 in either the astadr or the 
exitastadr arguments or both and the coordinates of the rectangle. 


exitastadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
read only 
by reference 


Exit AST routine. The exitastadr argument is the address of the entry mask 
to a procedure that is called at AST level whenever the pointer leaves the 
rectangle. 

To cancel the AST-enabling request of UISDC$SET_POINTER_AST for 
the EXIT AST routine only, specify 0 in the exitastadr argument and the 
coordinates of the rectangle. 


exitastprm 

VMS Usage: 
type: 
access: 
mechanism: 


user_arg 
longword 
read only 
by reference 
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Exit AST parameter. The exitastprm argument is the address of a single 
argument or data structure, such as an array or record, to be passed to the 
AST routine. Calls to UISDC$SET_POINTER_AST in VAX FORTRAN 
application programs should be coded as follows: %REF(%LOC(exitastprm)). 


Description 

UISDC$SET_POINTER_AST also allows an application to keep track of the 
pointer in its own way. This routine can be called any number of times for 
different rectangles. 

Note that an application need not enable both AST routines. It may specify 
one or the other. 

UISDC$SET_POINTER_A.ST can be used by the application to highlight 
the display or some other application-specific function, as the user moves 
the pointer over specific areas of the display window. This might be used to 
define a number of regions within a menu, and execute an AST when the 
pointer enters or leaves any of these regions. 

If both AST routines are enabled and the value 0 is specified in the astadr 
argument, the first AST routine is canceled. 

See the DESCRIPTION section of UIS$SET_BUTTON_AST for information 
about pointer region priorities. 




UlSDC Routines 19-61 

UISDC$SET_POINTER_PATTERN 


UISDC$SET_POINTER_PATTERN 

Allows an application to specify a special pointer cursor pattern. 

Format 

UISDC$SET_POINTER_PATTERN wd-id [, pattern-array, 

pattern—count, activex, 
activey][x,, y,, x^, y^; 
[flags] 

Returns 

UISDC$SET_POINTER_PATTERN signals all errors; no condition values are 
returned. 


Arguments 

wd—id 

VMS Usage; identifier 
type: longword (unsigned) 

access: read only 

mechanism; by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 

pattern—array 

VMS Usage; vector_word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

16 X 16 bit cursor pattern. The pattern—array argument is the address of 
one or more arrays of 16 words that represents a bitmap image of the cursor. 

Color and intensity applications can define two patterns that are also 
executable on monochrome systems. 
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If two arrays are specified in an application running on a single-plane system, 
the first array is used. 

NOTE: The bitmap image of the new pointer pattern is mapped in reverse 
order to display screen. 

pattern—count 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of 16- x 16-bit cursor pattern. The pattern _count argument is the 
address of a longword that contains the number of cursor pattern arrays 
defined in the pattern—array argument. 

activex, activey 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The activex and activey arguments are used to specify the actual bit in the 
cursor pattern that should be used to calculate the current pointer position. 
The arguments are expressed as bit offsets from the lower-left comer of the 
cursor pattern. 

xv Yi, xj, yj 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinates of the rectangle in the display window. 
The Xj and y^ arguments are the addresses of integers that define the lower- 
left comer of the rectangle in the display window. The Xi and y 2 arguments 
are the addresses of integer pixels that define the upper-right comer of the 
rectangle in the display window, 

flags 

VMS Usage: longword—mask 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Flags. The flags argument is the address of a longword mask whose bits 
determine whether or not the cursor is confined to the display window 
rectangle. 
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When specified, UIS$M_BIND_POINTER sets the appropriate bit in 
the mask. 


Description 

UISDC$SET_POINTER_PATTERN allows an application to specify a special 
pointer pattern to be used when the pointer is within the display window 
region specified by the optional rectangle. If no rectangle is given, then the 
entire display window is assumed. This function can be called any number 
of times for different rectangles. 

To disable UISDC$SET_JPOINTER_PATTERN, omit the pattern_array, 
pattern_count, activex, and activey arguments. 

See the DESCRIPTION section of UIS$SET_BUTTON_AST for information 
about pointer region priorities. 
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UISDC$SET^POINTER_POSITION 

Specifies a new current pointer position in device coordinates. It is only 
effective if the new pointer position is within the specified display window 
and visible. 


Format 

sfafus=UISDC$SET_POINTER^POSITION wd-id, x, y 


Returns 

Longword value returned as boolean in the variable status or RO (VAX 
MACRO) to indicate that the position is set. 

UISDC$SET_POINTER_POSITION signals all errors; no condition values 
are returned. 


Arguments 


wd—id 
VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UISDC$CREATE_ 
WINDOW for more information about the wd_id argument. 


x,y 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinates of the new pointer position. The x 
and y arguments are the addresses of integers that define the new pointer 
position. 
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UISDC$SET^POSITION 

Sets the current position for text output. The current position is the point of 
alignment on the baseline of the next character to be output. 


Format 

UISDC$SET_POSITION wd-id, x,y 


Returns 

UISDC$SET__POSITION signals all errors; no condition values are returned. 


Arguments 


wdUd 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wdLid argument. 


x,y 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Viewport-relative device coordinate pair. The x and y arguments are the 
addresses of integers that define the current position for text output. 
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UISDC$SET_TEXT_MARGINS 

Sets the text margins for a line of text. 

Format 

UISDC$SET_TEXT-MARGINS vd-id Jatb ,oatb ,x ,y 

,margin—length 

Returns 

UISDC$SET_TEXT_MARGINS signals all errors; no condition values are 
returned. 


Arguments 

wd—id 

VMS Usage: identifier 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window. See UIS$CREATE_ 
WINDOW for more information about the vd_id argument. 

iatb 

VMS Usage: longworcL^unsigned 
type: iongword (unsigned) 

access: read only 

mechanism: by reference 

Input attribute block number. The iatb argument is the address of a 
Iongword that identifies an attribute block to be modified. 

oatb 

VMS Usage: Iongword—unsigned 
type: Iongword (unsigned) 

access: read only 

mechanism: by reference 

Output attribute block number. The oatb argument is the address of a 
Iongword that identifies an attribute block. 
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VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Starting margin position. The x,y arguments are the addresses of integers 
that define a point on the starting margin in viewport-relative device 
coordinates. The starting margin is the minor text path when the angle 
of text slope equals 0 degrees. 

margin^fength 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Ending margin position. The margin—length is the address of an number 
that defines the distance from the starting margin to the end margin in 
viewport-relative device coordinates. 
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UISDC$TEXT 

Draws a series of encoded characters. 


Format 

UISDC$TEXT wd—id, atb, text—string [,x,y] [,ctllist ,ctllen] 


Returns 

UISDC$TEXT signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. See UIS$CREATE_ 
WINDOW for more information about the wd_id argument. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of a longword that 
specifies an attribute that modifies text output. 


text—String 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Text string. The text—string argument is the address of a character string 
descriptor of a text string. 






UlSDC Routines 19-69 
UISDC$TEXT 


^,y 

VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read oniy 
by reference 


Viewport-relative device coordinates pair. The x and y arguments are the 
addresses of integers that define the viewport-relative device coordinates of 
the starting point of text output at the upper-left comer of the character cell. 

If this argument is not specified, the current text position is used. (See the 
UlSDC$SET_ALIGNED_POSITION routine for more information.) 


ctllist 


VMS Usage: 
type: 
access: 
mechanism: 


vector_iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Text control formatting list. The ctllist argument is the address of an array 
of longwords that describe the font, text rendition, format, and positioning of 
text string fragments. See U1S$TEXT for a complete description of the text 
formatting control list. 


ctllen 


VMS Usage: 
type: 
access: 
mechanism: 


iongword—unsigned 
iongword (unsigned) 
read oniy 
by reference 


Length of the text formatting control list. The ctllen argument is the address 
of an integer that defines the length of the text formatting control list in 
longwords. 


Description 

Nonprinting characters such as tab and linefeed are not handled in any 
special way. The character is obtained from the font and is displayed like 
any other character. 




Appendix A 
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A.1 UlS Calling Sequences 

Table A-1 lists return values, entry point names, and parameter lists of all UIS 
routines. 


Table A-1 Summary of UIS Calling Sequences 


Return 

Value 

Routine 

Argument List 

seg_id 

UIS$BEGIN -SEGMENT 

vd—id 


UIS$CIRCLE 

vd—id, atb, center—x, center—y, 
xradius, [,start—deg] [,end—deg] 


UIS$CLOSE-WINDOW 

wd_id 

copy_id 

UIS$COPY-OBJECT^ 


vcm_id 

UIS$CRE ATE-COLOR-MAP 

vcm—size [,vcm—name] 



[, vcm —attributes] 

cms_id 

UIS$CREATE_COLOR-MAP-SEG 

vcm—id, [,devnam] [,place—mode] 
[,place—data] 

vd_id 

UIS$CREATE_DISPLAY 

xi, yj, X2, y2/ width, height 
[,vcm—id] 

kb_id 

UIS$CREATE-KB 

devnam 


UIS$CRE ATE -TERMINAL 

termtype [,title] [,attributes] 



[,devnam] [,devlen] 

tb_id 

UIS$CREATE_TB 

devname 

tr_id 

UIS$CREATE_TRANSFORMATION 

vd_id, xj, yj, X2, y2 [vdxj, vdy^ 
vdx 2 , vdy 2 ] 


Wax pascal and VAX PL/I applications must specify the obj—id argument. 





A-2 Summary of UlS Calling Sequences 
UiS Calling Sequences 


Table A-1 (Cent.) Summary of UIS Calling Sequences 


Return 

Value 

Routine 

Argument List 

wd_id 

UIS$CRE ATE-WINDOW 

vd—id, devnam [,title] [,Xi, yj, X2, 

72] [, width,height] [,attributes] 


UIS$DELETE_COLOR_MAP 

vcm—id 


UIS$DELETE_COLOR_MAP_SEG 

cms—id 


UIS$DELETE-DISPLAY 

vd—id 


UIS$DELETE-KB 

kb—id 


UIS$DELETE -OBJECT^ 

r obj—id 1 

1 seg—id J 


UIS$DELETE -PRIVATE 

obj —id 


UIS$DELETE-TB 

tb—id 


UIS$DELETE -TRANSFORMATION 

tr—id 


UIS$DELETE -WINDOW 

wd—id 


UIS$DIS ABLE -DISPLAY-LIST 

vd—id [,display—flags] 


UIS$DISABLE-KB 

kb—id 


UIS$DISABLE-TB 

tb—id 


UIS$DIS ABLE -VIE WPORT-KB 

wd—id 


UIS$ELLIPSE 

vd—id, atb, center—x, center—y, 
xradius, yradius, [,start—deg] 

[,end—deg] 


UIS$ENABLE-DISPLAY-LIST 

vd—id [, display—flags] 


UIS$ENABLE-KB 

kb-id [,wd_id] 


UIS$ENABLE-TB 

tb—id 


UIS$ENABLE-VIEWPORT-KB 

kb—id, wd—id 


UIS$END-SEGMENT 

vd—id 


UISSERASE 

vd-id [,xi yj, X2, y2] 


UIS$EXECUTE 

vd—id [,buflen] [,bufaddr] 

vd—id 

UIS$EXECUTE -DISPLAY 

buflen, bufaddr 


UIS$EXPAND-ICON 

wd—id [,icon—wd—id] [,attributes] 


UIS$EXTRACT-HEADER 

vd—id [,buflen, bufaddr] [,retlen] 


UIS$EXTRACT-OBJECT^ 

{ segZid } ,bufaddr] 

[,retlen] 


Wax pascal and VAX PL/I applications must specify the obj_id argument. 
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UIS Calling Sequences 


Table A-1 (Cont.) Summary of UIS Calling Sequences 


Return 

Value 

Routine 

Argument List 


UIS$EXTRACT_PRIVATE^ 

{ segZid } /bufaddr] 



[,retlen] 


UIS$EXTRACT_REGION 

vd—id [/Xi,yi,X2,y2] [,buflen 
,bufaddr] [,retlen] 


UIS$EXTRACT_TRAILER 

vd—id [,buflen, bufaddr] [,retlen] 

obj_id 

UIS$FIND_PRIMITIVE 

vd—id, xj, yi,X2,y2 [,context] 

[,extent] 

seg_Jd 

UIS$FIND_SEGMENT 

vd—id, Xj, yj, X2, y 2 > [/Context] 
[,extent] 


UIS$GET_ABS_POINTER_POS 

devnam, retx, rety 


UIS$GET_ALIGNED_POSITION 

vd—id, atb, retx, rety 

arc_type 

UIS$GET_ARC_TYPE 

vd—id,*atb 

index 

UIS$GET_BACKGROUND_INDEX 

vd—id, atb 

status 

UIS$GET_BUTTONS 

wd—id, retstate 

angle 

UIS$GET_CHAR_ROTATION 

vd—id, atb 

boolean 

UIS$GET_CHAR_SIZE 

vd—id, atb [,char], [width, height] 

angle 

UIS$GET_CHAR_SLANT 

vd—id, atb 


UIS$GET_CHAR_SP AGING 

vd_id, atb, dx, dy 

status 

UIS$GET_CLIP 

vd—id, atb [,xj, yj, X2, y2] 


UIS$GET_COLOR 

vd—id, index, retr, retg, retb [,wd—id] 


UIS$GET_COLORS 

vd—id, index, count, retr—vector, 
retg—vector, retb—vector [,wd—id] 

current—id 

UIS$GET_CURRENT_OBJECT 

vd—id 


UIS$GET_D 1 SPLAY_SIZE 

devnam, retwidth, retheight 
[,retresolx, retresoly] [,retpwidth 
retpheight] 

status 

UIS$GET_FILL -PATTERN 

vd—id, atb [,index] 


UIS$GET_FONT 

vd_id, atb, bufferdesc [,length] 


UIS$GET-FONT-ATTRIBUTES 

vd—id, ascender, descender, height. 



[,maximum—width] [,item—list] 


UIS$GET_FONT_SIZE 

fontid, text—string, retwidth, 
retheight 


Wax pascal and VAX PL/I applications must specify the obj_id argument. 
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Table A-1 (Cont.) Summary of UIS Calling Sequences 


Return 

Value 

Routine 

Argument List 


UIS$GET-HW-COLOR-INFO 

devnam [,type] [,indices] [,colors] 
[,maps] [,rbits] [,gbits] [,bbits] [Tbits] 
[,res—indices] [,regen] 


UIS$GET-INTENSITIES 

vd—id, index, count, reti—vector 
[,wd—id] 


UIS$GET-INTENSITY 

vd—id, index, reti [,wd—id] 


UIS$GET-KB-ATTRIBUTES 

kb—id [,enable—items] 

[,disable—items] [,click—volume] 

style 

UIS$GET-LINE-STYLE 

vd—id, atb 

width 

UIS$GET-L1NE -WIDTH 

vd—id, atb [,mode] 

next—id 

UIS$GET-NEXT-OBJECT^ 


type 

UIS$GET-OBJECT-ATTRIBUTES^ 


parent—id 

UIS$GET-PARENT-SEGMENT^ 

r obj—id 1 

1 seg_id / 

status 

UIS$GET-POINTER-POSITION 

vd—id, wd—id, retx, rety 


UIS$GET-POSITION 

vd—id, retx, rety 

prev—id 

UIS$GET-PREVIOUS-OBJECT^ 

Celled 

root—id 

UIS$GET-ROOT-SEGMENT 

vd—id 


UIS$GET-TB-INFO 

devnam, retwidth, retheight,retresolx, 
retresoly [,retpwidth, retpheight] 


UIS$GET-TB-P0SIT10N 

wd—id, retx, rety 

formatting 

UIS$GET-TEXT-FORMATTING 

vd—id, atb 


UIS$GET-TEXT-MARGINS 

vd—id, atb, x, y [,margin—length] 


UIS$GET_TEXT-PATH 

vd—id, atb [,major][,minor] 

angle 

UIS$GET_TEXT-SLOPE 

vd—id, atb 

vcm—id 

UIS$GET-VCM-ID 

vd—id 

boolean 

UIS$GET-VIEWPORT-ICON 

wd—id [icon—wd—id] 


UIS$GET-VIEWPORT-POSITION 

wd-id, retx, rety 


UIS$GET-VIEWPORT-SIZE 

wd—id, retwidth, retheight 

status 

UIS$GET-VISIBILITY 

vd—id, wd—id [,xj, yj [,X2, y2]] 


Wax pascal and VAX PL/I applications must specify the ob|_id argument. 
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Table A-1 (Cent.) Summary of UIS Calling Sequences 


Return 

Value 

Routine 

Argument List 

attributes 

UIS$GET_WINDOW_ATTRIBUTES 

wd—id 


UIS$GET_WINDOW_SIZE 

vd—id, wd—id, Xj, yj, X2, 

index 

UIS$GET_WRITING_INDEX 

vd—id, atb 

mode 

UIS$GET_WRITING_MODE 

vd—id, atb 


UIS$GET_WS_COLOR 

vd—id, color—id, retr, retg, retb 
[,wd—id] 


UIS$GET_WS_INTENSITY 

vd—id, color—id, reti [,wd—id] 


UIS$HLS_TO_RGB 

H, L, S, retr, retg, retb 


UIS$HSV_TO_RGB 

H, S, V, retr, retg, retb 


UIS$IMAGE 

vd—id, atb, xj, yj, X2, y2> 
rasterwidth, rasterheight, 
bitsperpixel, rasteraddr 


UISSINSERT-OBJECT^ 

1 obj—id 1 

1 seg-id / 


UIS$LINE 

vd-id, atb, Xj, yj [,X2, y^ [/-Xn/ yn]] 


UIS$LINE-ARRAY 

vd—id, atb, count, x—vector, 
y—vector 


UIS$MEASURE_TEXT 

vd—id, atb, text—string, retwidth, 
retheight ,[ctllist, ctllen] [,posarray] 


UIS$MOVE_AREA 

vd—id, Xj, yj, X2, y2/ new—x, new—y 


UIS$MOVE -VIEWPORT 

wd—id, attributes 


UIS$MOVE -WINDOW 

vd—id, wd—id, Xj, yj, X2, y^ 


UIS$NEW-TEXT-LINE 

vd—id, atb 


UIS$PLOT 

vd-id, atb, Xj, yj [,X2, y^ [, -Xn, yn]] 


UIS$PLOT-ARRAY 

vd—id, atb, count, x—vector, 
y—vector 


UISIPOP-VIEWPORT 

wd—id 

status 

UIS$PRESENT 

[major—version], [minor—version] 


UISSPRIVATE^ 

r obj-id 1 buffer 

1 vd—id J 


UIS$PUSH_VIEWPORT 

wd—id 

keybuf 

UIS$READ-CHAR 

kb—id [,flags] 


Wax pascal and VAX PL/I applications must specify the obj—id argument. 
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UIS Calling Sequences 


Table A-1 (Cont.) Summary of UIS Calling Sequences 
Return 

Value Routine Argument List 

UISSRESIZE -WINDOW 


UIS$RESTORE_CMS_COLORS 

UIS$RGB_TO_HLS 

UIS$RGB_TO_HSV 

UIS$SET_ADDOPT_AST 

UIS$SET_ALIGNED_POSITION 

UIS$SET_ARC_TYPE 

UIS$SET_BACKGROUND_INDEX 

UIS$SET_BUTTON_AST 

UIS$SET_CHAR-ROTATION 

UIS$SET-CHAR-SIZE 

UIS$SET_CHAR-SLANT 

UIS$SET_CHAR-SP AGING 

UIS$SET-CLIP 

UIS$SET_CLOSE-AST 

UIS$SET-COLOR 

UIS$SET-COLORS 

UIS$SET-EXPAND-ICON_AST 
UIS$SET-FILL -PATTERN 
UIS$SET_FONT 
UIS$SET-GAIN_KB-AST 
UIS$SET-INSERTION-POSITION 

UIS$SET-INTENSITIES 

UIS$SET_INTENSITY 

UIS$SET_KB_AST 


vd—id, wd—id [,new—abs—x, new— 
abs—y] [,new—width new—height] 
[,new—wc—xj, new—wc—yj, new— 
wc—X2, new—WC—y2] 
cms—id 

R, G, B, reth, retl, rets 

R, G, B, reth, rets, retv 

vd—id [,astadr [,astprm]] 

vd—id, atb, x, y 

vd—id, iatb, oatb, arc—type 

vd—id, iatb, oatb, index 

vd_id, wd—id [,astadr [,astprm] 

,keybuf] [,x^, yj, X2, y2] 

vd—id, iatb, oatb, angle 

vd—id, iatb, oatb [,char] [,width][,height] 

vd—id, iatb, oatb, angle 

vd—id, iatb, oatb, dx, dy 

vd—id, iatb, oatb [,xj, y^, X2, y2] 

wd—id [,astadr [,astpnn]] 

vd—id, index, R, G, B 

vd—id, index, count, r—vector, 
g—vector, b—vector 

wd—id [,astadr [,astprm]] 
vd—id, iatb, oatb [,index] 
vd—id, iatb, oatb, font—id 
kb—id [,astadr [,astprm]] 
obj—id 1 
seg—id y [/flags] 

vd—id J 

vd—id, index, count, i—vector 
vd—id, index, I 

kb—id [,astadr [,astprm], keybuf] 


^VAX PASCAL and VAX PL/I applications must specify the obj—id argument. 
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Table A-1 (Cont.) Summary of UIS Calling Sequences 


Return 

Value 


status 


Routine 

UIS$SET_KB_ATTRIBUTES 

UIS$SET_KB_COMPOSE2 
UIS$SET_KB_COMPOSE3 
UIS$SET_KB_KEYTABLE 
UIS$SET_LINE _STYLE 
UIS$SET_LINE _WIDTH 
UIS$SET_LOSE _KB_AST 
UIS$SET_MOVE _INFO_AST 
UIS$SET_POINTER_AST 

UIS$SET_POINTER_PATTERN 

UIS$SET_POINTER_POSITION 

UIS$SET_POSITION 

UIS$SET_RESIZE_AST 


UIS$SET_SHRINK_TO_ICON_AST 

UIS$SET_TB_AST 


UIS$SET_TEXT_FORMATTING 

UIS$SET_TEXT_MARGINS 

UIS$SET_TEXT_PATH 
UIS$SET_TEXT_SLOPE 
UIS$SET_WRITING-INDEX 
UIS$SET_WRITING_MODE 


Argument List 

kb—id [,enable—items] 

[,disable—items] [click—volume] 

kb—id [/table, tablelen] 

kb—id [/table, tablelen] 

kb—id [/table, tablelen] 

vd—id, iatb, oatb, style 

vd—id, itab, oatb, width [,mode] 

kb—id [,astadr [,astprm]] 

wd—id [,astadr [,astprm]] 

vd—id, wd—id [,astadr [,astprm]] [/Xj, 

Yl' ^ 2 ' Yz] [exitastadr [,exitastprm]] 

vd—id, wd—id [/pattern-array, 

pattern—count, activex, activey] [,xj, 

Vv ^2' Y2] ['flags] 

vd—id, wd_Jd, x, y 

vd—id, X, y 

vd—id, wd—id [,astadr [,astprm]] 
[,new—abs—X, new—abs—y] [,new— 
width, new—height] [,new—wc—Xj, 
new—wc—yj, new—wc—X2, 
new—WC—y2] 
wd—id [,astadr [,astprm]] 

tb—id, [/data—astadr, [data—astprm]], 
[,x—pos,y—pos] [/data—Xj, data—y^, 
data—X2, data—y2] [,button—astadr 
[/button —astprm],button —keybuf] 

vd—id, iatb, oatb,mode 

vd—id, iatb, oatb, x, y, 
margin—length 

vd—id, iatb, oatb, major[,mindr] 
vd—id, iatb, oatb, angle 
vd—id, iatb, oatb, index 
vd—id, iatb, oatb, mode 





A-8 Summary of UlS Calling Sequences 
UIS Calling Sequences 

Table A-1 (Cont.) Summary of UIS Calling Sequences 
Return 

Value Routine Argument List 

UIS$SHRINK_TO-JCON wd_id [,icon_wd_id] [,icon_flags] 

[,icon_name] [,attributes] 

UIS$SOUND_BELL devnam [,bell—volume] 

UIS$SOUND_CLICK devnam [,click_volume] 

status UIS$TEST_KB kb_id 

UIS$TEXT vd—id, atb, text—String [,x, y], [ctllist, 

ctllen] 

uis$transform_object 1 I "bMd J [ [,atb] 

^VAX PASCAL and VAX PL/I applications must specify the obj—id argument. 





Appendix B 

Summary of UlSDC Calling Sequences 

B.1 UlSDC Calling Sequences 

The following table summarizes UlSDC calling sequences. 


Table B-1 Summary of UlSDC Calling Sequences 


Return 

Value 

Routine 

Argument List 

dop 

UISDC$ALLOCATE_DOP 

wd_id, size, atb 


UISDC$CIRCLE 

wd_id, atb, center_x, center_y, 
xradius [,start_deg] [,end_deg] 


UISDC$ELLIPSE 

wd_id, atb, center_x, center_y, 
xradius, yradius, [,start_deg] 
[,end_deg] 


UISDC$ERASE 

wd-Jd [,Xi,y|,X2, y2] 


UISDC$EXECUTE_DOP_ASYNCH 

wd_id, dop, iosb 


UISDC$EXECUTE _DOP_SYNCH 

wd_id, dop 


UISDC$GET_ALIGNED_POSITION 

wd_id, atb, retx, rety 

boolean 

UISDC$GET_CHAR_SIZE 

wd_Jd, atb [,char],[width][,height] 

status 

UISDC$GET_CLIP 

wd_id, atb [,xi,yi, X2,y2] 

status 

UISDC$GET_POINTER_POSITION 

wd_id, retx, rety 


UISDC$GET_POSITION 

wd_id, retx, rety 


UISDC$GET_TEXT_MARGINS 

wd_id, atb, x, y [,margin_length] 

status 

UISDC$GET_VISIBILITY 

wd_id [,xi,yi [,X2,y2]] 


UISDC$IMAGE 

wd_id, atb, Xj, y^, X2, 
rasterwidth, rasterheight, 
bitsperpixel, rasteraddr 


UISDCSLINE 

wd_id, atb, xi,yi, [,X2,y2 [,...xn, y 
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Table B-1 (Cont.) Summary of UISDC Calling Sequences 

Return 

Value Routine Argument List 

UISDC$LINE—ARRAY wd—id, atb, count, X—vector, 

y—vector 

bitmap—id UISDC$LOAD—BITMAP wd—id, bitmap—adr, bitmapJen, 

bitmap—width, bits—per—pixel 

UISDC$MEASURE—TEXT wd—id, atb, text—string, retwidth, 

retheight [,ctllist ,ctllen] [,posarray] 

UISDC$MOVE—AREA wd—id, xj,yi,X2, i^cw—x, new—y 

UISDC$NEW-TEXT_LINE wd-id, atb 

UISDC$PLOT wd—id, atb, X2,y2, [,X2,y2 [,...xn, yn]] 

UISDC$PLOT—ARRAY wd—id, atb, count, x—vector, 

y—vector 

UISDC$QUEUE-DOP wd-id, dop 

UISDC$READ—IMAGE wd—id, Xj, yj, Y2> rasterwidht, 

rasterheight, bitsperpixel, rasteraddr, 
rasterlen 

UISDC$SET-ALIGNED-POSITION wd_id, atb, x, y 

UISDC$SET—BUTTON—AST wd—id [,astadr, [astprm], keybuf] 

[,xi, yj, X2, y2] 

UISDC$SET—CHAR—SIZE wd—id, iatb, oatb [,char][,width][,height] 

UISDC$SET—CLIP wd—id, iatb, oatb [,xj, yj, X2, y2] 

UISDC$SET—POINTER—AST wd—id [,astadr [astprm]] [,X|, yj, X2, 

y2] [/Cxitastadr [,exitastprm]] 

UISDC$SET-POINTER-PATTERN wd-id [,pattem-array, 

pattern—count, activex, activey] 

[,xi, yi,X2, y2][,flags] 

status UISDC$SET-POINTER-POSITION wd-id, x, y 

UISDC$SET-POSITION wd-id, x, y 

UISDC$SET-TEXT-MARGINS wd-id, iatb, oatb, x, y, 

margin—length 

wd—id atb, text—string [,x, y] 

[,ctllist, ctllen] 


UISDC$TEXT 





Appendix C 
UlS Fonts 


C.1 Overview 

This appendix contains figures and tables illustrating the UIS multinational character 
and technical fonts and font names contained in the directory SYS$FONT. 


C.2 UIS Multinational Character Set Fonts 

There are 14 multinational character set font files in the directory SYS$FONT. 

The figure captions below identify each UIS font with an arbitrarily assigned font 
number. For more information about font characteristics, match this number with the 
appropriate table in Section C.2.1. 

Figure C-1 Font 1 


ABCDEFGHIJKLMNOPQRSTUVIUXYZ 
ab c d e f gb i jkl m n o p q rs tu vwx y z 
1234567890-=!e##%^&»()_+ 


ZK-4565-85 

Figure C-2 Font 2 

f=lBCDEFGHIJKLMNOPQRSTUVUJXYZ 
abodefghijklmnopqrstuvwxyz 
1234567890 - = ! () _ + 

<>, . /?; I '"M C3 {} 


ZK-4566-85 
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Figure C-3 Font 3 
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ZK-4567-85 


Figure C-4 Font 4 
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ZK-4568-85 


Figure C-5 Font 5 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghijklmnopqrstuvwxyz 
1234567890-=!0 _+ 
<>,./?; :'"\l [] {} 


ZK-4569-85 
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Figure C-6 Font 6 

MCDEFGHimmOPQRSTIIViliXYZ 
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ZK-4570-85 

Figure C-7 Font 7 

RBCDEFGHIJKLMNOPqRSTUVNXYZ 
abcdefghijklnnopqrstuvuxyz 
1234567890-=! 

<>,./?; :''MC 3 » 

ZK-4571-85 


Figure C-8 Font 8 

ABCDEFGHI3KLMN0PQRSTUUWXYZ 

abcdefgbijKlmnopqrstuvwxyz 

1234567890-=I@#OJ{^&*()_+ 


ZK-4572-85 
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Figure C-9 Font 9 


ABCD E FGH1 3K LMNOPQRSTUVWXYZ 
abcdefghijKlmnopqrstuvwxyz 
1234567890-=!)_+ 
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ZK-4573-85 


Figure C-10 Font 10 

ABCDEFGHIJ KLMNOPQRSTUUUXYZ 
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ZK-4574-85 


Figure C-11 Font 11 

ABCD E FGH1 3K LMNOPQRSTUVWXVZ 
abcdefghijklmnopqrstuvwxyz 
1234567890 -=! 

ZK-4575-8B 
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Figure C-12 Font 12 
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ZK-4576-85 


Figure C-13 Font 13 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
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ZK-4577-85 

Figure C-14 Font 14 

ABCDEFGHI JKI-mNOPqRSTUVMXYZ 
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ZK-4578-85 


C.2.1 UIS Multinational Character Set Font Specifications 

Each font file name, included in the following table captions contains typographical 
information about a UIS font. The accompanying tables analyzes the first 16 
characters of the font file name. 
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Table C-1 Font 1—DTABER0003WK00PG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

0 

Proportionally spaced 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


Table C-2 Font 2—DTABER0I03WK00GG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

I 

9 pitch (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-3 Font 3—DTABER0M03CK00GG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

M 

13 pitch (monospaced) 

9-11 

Type size 

03^36 

12 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 
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Table C-4 Font 4—DTABER0R03WKO0GG0001UZZZZO2AO0O 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-5 Font 5—DTABER0R07SK00GG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

07S36 

28 points (280 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 


Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-6 Font 6—DTERM1NG03CKO0PG0001UZZZZ02AO00 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TERMIN 

Terminal 

8 

Spacing 

G 

7 pitch (monospaced) 

9-11 

Type size 

03^36 

12 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 
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Table C-7 Font 7—DTERMINM06OK00PG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TERMIN 

Terminal 

8 

Spacing 

M 

13 pitch (monospaced) 

9-11 

Type size 

O 6 O 36 

24 points (240 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


Table C-8 Font 8—DTABER0003WK00GG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

0 

proportionally spaced 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-9 Font 9—DTABER0G03CK00GG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

G 

7 pitch (monospaced) 

9-11 

Type size 

03C36 

12 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 
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Table C-10 Font 10—DTABER0I03WK00PG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

1 

9 (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO 36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


Table C-11 Font 11—DTABER0M06OK00GG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

M 

13 pitch (monospaced) 

9-11 

Type size 

O 6 O 35 

24 points (240 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 

Table C 

-12 Font 12—DTABER0RO3WK0OPG0O01UZZZZ02AO00 

Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 
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Table C-13 Font 13—DTABER0R07SK00PG0001UZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TABERO 

Taber 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

07S36 

28 points (280 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 

Table C 

-14 Font 14—DTERMINMO3CK0OPG001UZZZZ02A000 

Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

TERMIN 

Terminal 

8 

Spacing 

M 

13 pitch (monospaced) 

9-11 

Type size 

03^36 

12 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


C.3 UlS Technical Character Set Fonts 

There are 12 technical character set font files in SYS$FONT. The figure captions 
below identify each UIS font with an arbitrarily assigned font number. For more 
information about font characteristics, match this number with the appropriate table 
in Section C.3,1. 

Figure C-15 Font 15 
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Figure C-16 Font 16 
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Figure C-17 Font 17 
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Figure C-18 Font 18 
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Figure C-19 Font 19 
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Figure C-20 Font 20 
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Figure C-21 Font 21 

^uajT + poricoCu 

Z'v^W"'"'5 M * y 
j ^ r" = ^ 

ZK-5381-86 
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Figure C -23 
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Figure C -24 
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Figure C -25 Font 25 
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Figure C-26 Font 26 
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C.3.1 UIS Technical Character Set Font Specifications 

Each technical font file name, included in the following table captions contains 
typographical information about a UIS technical character set font. The accompany¬ 
ing table describes the first 16 characters of the technical font file name. 


Table C-15 Font 15—DVWSVT0G03CK00GG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

G 

7 pitch (monospaced) 

9-11 

Type size 

03^36 

12 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 
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Table C-16 Font 16—DVWSVT0G03CK00PG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

G 

7 pitch (monospaced) 

9-11 

Type size 

03C36 

12 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


Table C-17 Font 17—DVWSVT0I03WK00GG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

I 

9 pitch (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^6 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-18 Font 18—DVWSVT0I03WK00PG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

I 

9 pitch (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 
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Table C-19 Font 19—DVWSVT0N03CK00GG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

N 

14 pitch (monospaced) 

9-11 

Type size 

03^36 

120 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO 36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-20 Font 20—DVWSVT0N03CK00PG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

N 

14 pitch (monospaced) 

9-11 

Type size 

O 3 C 36 

12 points (120 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


Table C-21 Font 21—DVWSVT0N06OK00GG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

N 

14 pitch (monospaced) 

9-11 

Type size 

O 6 O 36 

24 points (240 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 
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Table C-22 Font 22—DVWSVT0N06OK00PG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

N 

14 pitch (monospaced) 

9-11 

Type size 

O 6 O 36 

24 points (240 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 


Table C-23 Font 23—DVWSVT0R03WK00GG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-24 Font 24—DVWSVT0R03WK00PG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

03W36 

14 points (140 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO36 

Roman 

15 

Weight 

P 

Bold 

16 

Proportion 

G 

Regular 
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Table C-25 Font 25—DVWSVT0R07SK00GG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

07S36 

28 points (280 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

0^36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 


Table C-26 Font 26—DVWSVT0R07SK00GG0001QZZZZ02A000 


Field 

Field Name 

Value 

Meaning 

1 

Registration code 

D 

Registered by DIGITAL 

2-7 

Type Family ID 

VWSVTO 

VAXstation Technical Character Set 

8 

Spacing 

R 

18 pitch (monospaced) 

9-11 

Type size 

07S36 

28 points (280 decipoints) 

12 

Scale factor 

K 

1 (normal) 

13-14 

Style 

OO 36 

Roman 

15 

Weight 

G 

Regular 

16 

Proportion 

G 

Regular 








Appendix D 
UlS Fill Patterns 


All fill patterns are located together in SYS$FONT in a separate file named 
DEUISPATAAAAAAFOOOOOOOOODA.VWS$FONT. This file can be accessed with 
the logical name UIS$FILL—PATTERNS. 

The pairs of fill patterns shown in the following figures were drawn in OVERLAY 
writing mode on a white background. The figure caption contains the symbol name 
for each fill pattern. The symbol name represents an index to the appropriate fill 
pattern. 

Symbol names are located in language-specific symbol definition files in SYS$LIBRARY. 
Refer to Table 6-2 for a list of symbol definition files. 


Figure D-1 PATT$C_VERT1-1 and PATT$C-VERT1_3 















































































































D-2 UlS Fill Patterns 


Figure D-2 PATT$C_VERT2_2 and PATT$C_VERT3_1 



ZK-4585-85 


Figure D-3 PATT$C_VERT1_7 and PATT$C_VERT2_6 



Figure D-4 PATT$C_VERT4_4 and PATT$C_VERT6_2 



ZK-4587-85 
























































































































UlS Fill Patterns 









































































































D-4 UlS Fill Patterns 


Figure D-8 PATT$C_HORIZ4_4 and PATT$C_HORIZ6_2 



ZK-4591-85 


Figure D-9 PATT$C_GRID4 and PATT$C_GRID8 
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Figure D-10 PATT$C_UPDIAG1_3 and PATT$C_UPDIAG2_2 
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D-6 UlS Fill Patterns 
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UlS Fill Patterns D-7 


Figure D-17 PATT$C_BRICK_HORIZ and PATT$C_BRICK_VERT 



ZK-4600-85 


Figure D-18 PATT$C_BRICK_DOWNDIAG and PATT$C_BRICK_UPDIAG 
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Figure D-19 PATT$C_GREY4_16D and PATT$C_GREY12_16D 
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Figure D-20 PATT$C_BASKET_WEAVE and PATT$C_SC ALE-DOWN 



ZK-4603-85 


Figure D-21 PATT$C_SCALE_UP and PATT$C_SC ALE-RIGHT 



ZK-4604-85 


Figure D-22 PATT$C-SC ALE-LEFT and PATT$C-GREY1-16 
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Figure D-23 PATT$C_GREY2_16 and PATT$C_GREY3_16 



Figure D-24 PATT$C_GREY4_16 and PATT$C_GREY5_16 
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Figure D-25 PATT$C_GREY6_16 and PATT$C_GREY7_16 



ZK-4609-8S 



































































































































































































































































































D-10 UiS Fill Patterns 


Figure D-26 PATT$C_GREY8_16 and PATT$C_GREY9_16 



ZK-4610-85 


Figure D-27 PATT$C_GREY10_16 and PATT$C_GREY11_16 



ZK-4611-85 


Figure D-28 PATT$C_GREY12_16 and PATT$C_GREY13_16 
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Figure D-29 PATT$C_GREY14_16 and PATT$C_GREY15_16 
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Appendix E 
Error Messages 


This appendix contains the messages which may be generated by the Micro VMS 
workstation graphics software. Each message description consists of the message 
text, a brief explanation of the message, and the possible remedy. 

BAD_ATB, Illegal attempt to modify attribute block 0 (read-only). 

Explanation: An attempt was made to modify an attribute in attribute block #0, 
which is defined to be read-only. The modification request is ignored. 

User Action: Check for a programming error. 

BAD_DISP, Display list has been corrupted. 

Explanation: An illegal display list type code has been encountered while 
traversing a display list. 

User Action: Check the validity of the UIS metafile you are executing. 

BAD—KB, Illegal virtual keyboard identifier. 

Explanation: An illegal virtual keyboard identifier was given to a UIS routine as 
an argument. 

User Action: Check for a programming error. 

BADTITLE, Illegal window title string. 

Explanation: An illegal window title string was passed when attempting to 
create a window. 

User Action: Shorten the title. 

BAD—TR, Illegal transformation identifier. 

Explanation: An illegal transformation identifier was given to a UIS routine as 
an argument. 

User Action: Check for a programming error. 



E-2 Error Messages 


BAD_VD, Illegal virtual display identifier. 

Explanation: An illegal virtual display identifier was given to a UIS routine as 
an argument. 

User Action: Check for a programming error. 

BAD_VOLUME, Illegal volume level specified. 

Explanation: An illegal volume level was given to the UIS$SOUND routine. 
The volume must be in the range of 1 to 8. 

User Action: Check for a programming error. 

BAD_WD, Illegal display window identifier. 

Explanation: An illegal display window identifier was given to a UIS routine as 
an argument. 

User Action: Check for a programming error. 

BADWDPL, Window placement attribute list has an invalid format. 

Explanation: An illegal window attribute list was passed when attempting to 
create a window. 

User Action: Check for illegal item types in the window attribute list. 

INSFARG, Insufficient arguments. 

Explanation: A required argument was not specified. 

User Action: Check for a programming error. 

NO—FONT, The font cannot be found. 

Explanation: An attempt was made to reference a font which could not be 
satisfied, even by looking for other fonts which might be similar. All references 
to the attribute block specifying this font will produce this same error. The 
program may continue after this error. 

User Action: Specify font contained in the SYS$FONT directory. 

NOURG, Cannot disable region AST because no matching region can be found. 

Explanation: An attempt was made to disable a user region AST by using 
an ASTADR=0 and the region boundary used in the original enable request. 
However, no entry can be found with matching boundary coordinates. The 
program must ensure that the boundary coordinates match exactly in order to 
disable an existing request. 

User Action: Check for a programming error. 



Error Messages e-3 


VPTOOSMALL, Requested size of the viewport is too small. 

Explanation: The desired size of the viewport is too small to be displayed on the 
screen. 

User Action: Request larger viewport. 




Appendix F 
Obsolete Routines 


The following routines are obsolete and will no longer be documented. 
• UIS$GET_LEFT_MARGIN 


UIS$SET_LEFT_MARGIN 

UISDC$GET_LEFT_MARGIN 

UISDC$SET_LEFT_MARG1N 




Glossary 


array: Any organized arrangement of related elements. 

address: A 32-bit VAX address positioned in a longword item. 

argument list: A vector of longwords that represents a procedure 
parameter list and possibly a function value. 

aspect ratio: The ratio between the height and width of a graphic object. 
In reference to a virtual display, the aspect ratio is a comparison of the 
relative proportions of the vertical and horizontal components of objects 
in the virtual display. 

attribute: A quality or characteristic that determines the appearance of an 
object displayed on the screen. For example, the attributes of a line are its 
width, style, and color. 

baseline: The side of a geometric object or drawing from which the object 
is constructed or drawn. 

call: The transfer of processing control to a specified subroutine. 

Cartesian coordinate system: A system of measuring distances in which 
the location of a point is defined as its distance from two straight lines that 
intersect at right angles. It is used as the basis of coordinate measurements 
in computer graphics systems. 

clipping: Any graphic data outside a specified boundary that are removed 
from the display or the file. It is often used in mapping applications to 
remove data that would otherwise confuse the image being represented. 

clipping rectangle: The physical limit in a graphics file beyond which data 
are either not visible or automatically deleted. 



2-Glossary 


condition vaiue: A 32-bit value used to identify uniquely an exception 
condition. A condition value may be returned to a calling program as a 
function value or signaled using the VAX signaling mechanism. 

current text position: The world coordinate position that defines the 
current drawing location for UIS text routines. 

cursor: A position indicator used on a display screen to pinpoint where 
data will be displayed. The cursor is often represented by a blinking block 
character. 

data tablet: The name for a variety of data entry devices consisting of a 
stylus (pen) or puck, and a board with a coordinate grid superimposed 
on its surface. When the input object (pen or puck) touches the board, 
graphic information describing the location of the point touched is 
transmitted as input information. The data tablet is an absolute pointing 
device. 

descriptor: A mechanism for passing parameters in which the address of a 
descriptor is provided in the longword argument list entry. The descriptor 
contains the address of the parameter, the data type, size, and additional 
information needed to describe fully the data passed. 

device coordinates: The device-dependent Cartesian coordinates that 
specify positions on the Micro VMS display screen. Sometimes referred to 
as physical device coordinates, these coordinates are involved in mapping 
of the display window to the display screen. 

display viewport: The area of the physical display screen into which 
a display window is mapped. It is the physical region on the terminal 
screen that is created by the Micro VMS workstation and controlled by the 
user. 

display window: The portion of world coordinate space mapped to the 
graphics viewport. The display window is used to control how much of 
the virtual display is potentially available for the user to view. 

emulated terminal: A virtual I/O device whose programming interface 
matches the programming interface of a specific physical terminal and 
whose appearance on the Micro VMS workstation screen is similar to the 
appearance of the physical terminal. 

exception condition: A hardware- or software-detected event that alters 
the normal flow of instruction execution. 



Glossary-3 


font: A specific representation of a text character. The attributes of a font 
are family (type face), type size, and rendition. 

function: A procedure that returns a single value according to standard 
conventions. If additional values are returned, they are returned by means 
of the argument list. 

graphics data tabiet: An optional input device that consists of a rigid 
tablet, and a puck containing a crosshair cursor and a number of buttons, 
or a pen. The position of the cursor can be read by application programs. 
The tablet is an absolute pointing device. 

graphics display: Describes any graphics data output device that can 
present an image of graphic data derived from a computer graphics 
system. An example of a graphics display is a display screen or a printer. 

graphic object: The graphic image constructed by an application program 
using UIS routines. A graphic object could be a simple line or a complex 
drawing. 

graphics text: Text output primitives displayed using the UIS routines. 

grey scale: The level of brightness that describes the illumination of a 
cathode-ray tube screen. 

image: The output form of on-line graphics data. That is, a displayed or 
drawn representation of a graphics file. 

language-support procedures: Procedures called implicitly to implement 
high-level language constructs. They are not intended to be called 
explicitly from user programs. 

library procedures: Procedures called explicitly using the equivalent 
of a CALL statement or function reference. They are usually language 
independent. 

mapping: Any process by which a graphics system translates graphic data 
from one coordinate system into a form useful on another coordinate 
system. 

mouse: A data entry device consisting of a small control box, on rollers, 
that is pushed along a surface and transmits its changing position to the 
workstation. Often, function keys or buttons are mounted on the device 
and can be used to enter information or make selections. This device is 
the user's means for pointing to and selecting objects on the screen. The 
mouse is a relative pointing device. 
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output primitive: A part of an image created with UIS procedures, such as 
a graphics object or a text string, that has a specific appearance. Values of 
attributes determine some aspects of this appearance. 

physical device coordinates: Device-dependent Cartesian coordinates 
that specify the addressable points on a physical device. 

pixel: The density of one picture element. The smallest displayable unit 
on a display screen. 

pointer: The cursor on the screen that tracks movements of the mouse. 
The shape of the pointer depends upon its current use. 

primitives: The most basic graphic entities available on a graphics system, 
such as points, line segments, or characters. 

procedure: A closed sequence of instructions that is entered from, and 
returns control to, the calling program. 

puck: A hand-held graphics device with a cross hair sight used to pinpoint 
coordinates on a data tablet or digitizer. 

raster: A pattern of scanning lines in a cathode-ray tube which divide the 
display area into addressable points. 

reference: A mechanism for passing parameters in which the address of 
the parameter is provided in the longword argument list by the calling 
program. 

resizing: The process of scaling or changing the size of a graphics viewport 
according to predetermined data. 

stretchy box: The outline of a clipping rectangle used in the UIS 
functions PRINT SCREEN and RESIZE WINDOW. This rectangle can 
be manipulated to assume practically any rectangular dimensions and is 
limited only by the display screen size. 

subroutine: A procedure that does not return a value according to the 
standard conventions. If values are returned, they are returned by means 
of the argument list. 

transformations: The ability of the UIS graphics system to manipulate 
coordinate data. Transformations occur when mapping one coordinate 
system into another coordinate system. 
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tablet: A device which can convert a stylus position into Cartesian 
coordinates. When connected to a graphic display screen, it can control 
the real-time positioning of a cursor or pointer, 

UlS: The graphics software called User Interface Services, 

value: A mechanism for passing input parameters in which the actual 
value is provided in the longword argument list entry by the calling 
program. 

viewport: A rectangle that maps the image defined by a window into a 
virtual display onto the display screen. The user controls the visibility and 
placement of viewports on the physical screen, 

viewing transformation: The viewing transformation is the process of 
mapping the world coordinates of a graphic object in a display window to 
the device coordinates of a display viewport on a physical display device. 

virtual display: The world coordinate space defined by an application 
program. An application program uses a virtual display as a place in 
which to build graphic images. It can be thought of as a virtual output 
device that has the properties of a physical screen, but is not necessarily 
visible on a physical screen. 

virtual keyboard: A virtual input device associated with a window. When 
users select a window into a virtual display with a virtual keyboard, input 
from the physical keyboard is directed to the virtual keyboard and can be 
read by an application program. 

window: A defined area within a virtual display that can be used for 
viewing the virtual display. A window is the area of the virtual display 
that is to be mapped to a viewport. 

world coordinates: Device-independent Cartesian coordinates defined by 
the application program in order to describe objects to UIS. 

X axis: The reference line of a rectangular coordinate system used to 
determine horizontal distance and positions. 

x-height: The height of lowercase characters excluding descenders and 
ascenders. 
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y axis: The reference line of a rectangular coordinate system used to 
determine vertical distance and positions. 

zooming: The process by which the perspective on a displayed graphics 
file moves rapidly closer or farther from the operator. 
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A 

Arc type 

See Attribute 
Argument 

characteristics of 

passing mechanism, 6-3 
Argument passing mechanism 
%DESCR, 6-7 
%LOC, 6-7 
%REF, 6-7 
%VAL, 6-7 
Aspect ratio, 8-3 
AST-enabling routine, 17-2 
AST routine, 17-1 

Asynchronous system trap (AST) routine, 
17-1 

Attribute, 3-2, 9-1 

See also Attribute block 
See also Attribute block 0 
See also Segment 
description of, 3-2 
general, 3-2, 3-3, 9-8 

background color index, 3-3, 9-8 
modifying, 9-3, 11-1 
writing color index, 3-3, 9-9 
writing mode, 3-3, 9-9 
graphics, 3-2, 3-5, 11-1 
arc type, 3-5, 11-3 
fill patterns, 3-5, 11-2 
line style, 3-5, 11-4 
line width, 3-5, 11-4 
text, 3-2, 3-3, 10-21 
centering, 10-24 
character rotation, 10-24 
character scaling, 10-25 


Attribute 

text (cont'd.) 

character slant, 10-25 
character spacing, 3-3, 10-24 
fonts, 3-3, 10-23 
formatting mode, 10-24 
justification, 10-24 
kerning, 10-24 
leading, 10-24 
left margin, 3-3 
line spacing, 10-24 
modifying, 10-22 
path, 10-25 
slope, 10-25 
text margin, 10-24 
window 

clipping rectangle, 3-5 
windowing 

clipping rectangle, 11-14 
Attribute block, 3-6, 9-2 
See also Attribute 
Attribute block 0, 3-6, 9-2 
See also Attribute 
Attribute routine, 9-3, 10-22, 11-1 

B 

Background color index 
See Attribute 
Baseline 

See Text output 
Built-in function 

See Argument passing mechanism 
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C 

Callable routine, 6-1 
Calling sequence, 6-2 

argument characteristics, 6-3 
argument list, 6-2 
call type, 6-2 
entry point name, 6-2 
routine name, 6-2 
summary 
UlS, A-1 
UISDC, B-1 
CALL statement, 6-1 
Character rotation 
See Attribute 
Character scaling 
See Attribute 
Character slant 
See Attribute 
Chara ter spacing 
See Attribute 
Clipping rectangle 
see Attribute 
Color 

See color system 
Color map 

See Color system 
Color map segment 
See Color system 
Color system 
color, 4-1 

preferred, 4-11 
standard, 4-11 
color map 

hardware, 4-3 
segment, 4-11 
virtual, 4-7 
color regeneration 

characteristics, 4-13 
color value conversion, 4-12 
compatibility feature 
color, 4-12 
intensity, 4-12 
monochrome, 4-12 


Color system (cont'd.) 
hardware color map 

reserved entries, 4-9 
intensity, 4-1 
model 

color, 4-6 
HLS, 4-6 
HSV, 4-6 
RGB, 4-6 
monochrome, 4-1 
palette, 4-6 
palette size 

direct color, 4-6 
mapped color, 4-7 
pixels, 4-1 
planes, 4-2 
realized color, 4-13 
set color, 4-13 
value 

color, 4-6 
direct color, 4-3 
intensity, 4-6 
mapped color, 4-3 
pixel, 4-2 

virtual color map, 4-7 
characteristics, 4-9 
initialization, 4-9 
private, 4-11 
shareable, 4-11 
swapping, 4-7 
Communication tool, 1-6 
keyboard, 1-7 
pointer 

mouse, 1-6 
tablet, 1-6 

Condition value signaled, 6-9 

Constant, 6-9 

Coordinate 

device-dependent 
absolute, 2-6 
viewport-relative, 2-7 
device-independent 
normalized, 2-5 
world, 2-4 
types of, 7-2 
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Coordinate system 
Cartesian, 2-3 
device-dependent, 2-6 
absolute, 2-3 
viewport-relative, 2-3 
device-independent, 2-3 
normalized, 2-3 
world, 2-3 

D 

Data definition file 

See Data description file 
Data description file 
entry point, 6-9 
message, 6-10 
symbol definition, 6-9 
Display list, 2-13, 13-1 
disabling, 13-5 
editing, 13-21 
enabling, 13-5 
generic encoding, 2-13 
metafile, 2-13 
private data, 15-19 
root segment, 13-2 
segment, 13-1 
creating, 13-5 
modifying attributes, 13-21 
walking, 13-6 
Display list routine, 13-1 
Display viewport, 2-10, 7-6 
banner, 8-4 

creating, 7-6, 8-2 to 8-5 
mapping windows to, 2-10 
number, 8-3 

placement, 8-4, 8-12 to 8-25 

popping, 8-12 

pushing, 8-12 

scaling, 2-11 

shrinking, 17-13 

size, 8-3 

Display window, 2-9, 7-6 
clipping rectangle, 2-9 
closing, 17-13 
creating, 7-6, 8-2 to 8-5 
deletion, 8-7 


Display window (cont'd.) 
distortion, 8-3 
magnification, 8-3 
number, 8-3 
placement, 8-12 to 8-25 
resizing, 17-13 
scaling, 2-11 
size, 8-3 

viewing objects, 2-9 
Distortion 

See Distortion of graphic objects 
Distortion of graphic objects, 2-12 
cause of, 2-12 
correction of, 2-12 
transformations, 2-12 

E 

Error messages, E-1 to E-3 

F 

Fill pattern, 11-2, D-1 
See also Attribute 
Font 

See also Attribute 
font file names, 10-23 
multinational, 10-23 
multinational character, C-1 
SYS$FONT, 10-23 
technical, 10-23, C-10 
Format heading 

See Routine format 
FORTRAN built-in function, 6-7 
Function reference, 6-1 

G 

General attribute 
See Attribute 
Generic encoding 
See Display list 

Graphic object, 3-2, 7-4 to 7-6 
attributes, 3-2 
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Graphic object (cont'd.) 
creating, 7-4 
geometric shapes 
circle, 7-4 
ellipse, 7-4 
line, 7-4 
point, 7-4 
polygon, 7-4 
raster image, 7-5 
text, 7-5 

viewing transformation, 3-7 
Graphics attribute 
See Attribute 
Graphics capability, 1-7 
Graphics routine, 7-4 
description of, 3-2 

H 

Hardware color map 
See Color system 
Human interface, 1-5 

See also Terminal emulation 
capabilities, 1-5 
interaction with user, 1-5 

I 

Inquiry routine, 12-1 
invoking, 12-7 

K 

KB icon 

See Virtual keyboard 
Keyboard 

See Physical keyboard 
See Virtual keyboard 
Keyboard routine, 17-3 

L 


Line style 

See Attribute 
Line width 
See Attribute 

M 

Mapping 

See Display viewport 
Mapping display window 
See Display viewport 
Margin setting 
See Attribute 
Message definition file 
See data description file 
Metafile 

See Display list 
Mouse, 5-2 

menu selection, 5-2 

P 

Physical keyboard, 5-4 
Pixel 

See Color system 
Pointer, 5-2, 17-8 
See also Mouse 
See also Tablet 
alternate pattern, 17-10 
Pointer routine, 17-8 
Preferred color 
See Color system 
Private data 
See display list 
Program execution, 6-13 
compiling, 6-13 
invoking the editor, 6-13 
linking, 6-14 
running, 6-14 

Programming example, 6-12 
Puck, 5-3 


Line spacing 
See Attribute 
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R 


Routine 

inquiry 

AST-enabling, 17-2 
attribute, 9-3, 10-22, 11-1 
display list, 13-1 
graphics, 7-4 
keyboard, 17-3 
pointer, 17-8 
windowing, 8-1 
Routine format 

format heading, 18-3 


S 


Scaling 

See display viewport 
See Display window 
Segment, 3-7 

See also Attribute 
See Display list 
Segmentation 
See Display list 
Standard color 
See Color system 
Stylus, 5-3 
Swapping color map 
See Color system 
Symbol definition file 
See data description file 


T 


Tablet, 5-3 
puck, 5-3 
stylus, 5-3 

Terminal emulation, 1-6 
TEK4014, 1-6 
VT220, 1-6 
Text attributes 
See Attribute 
Text centering 
See Attribute 


Text justification 
See Attribute 
Text output, 7-4 to 7-6 
alignment, 10-25 
baseline, 10-25 
creating, 7-4 
Text path 

See Attribute 
Text routine 

decription of, 3-2 
Text slope 
See Attribute 
Transformation 
attribute, 14-17 
geometric, 3-7, 14-1 

complex rotation, 14-9 
complex scaling, 14-5 
COPY, 14-10 
differential scaling, 14-7 
MOVE, 14-10 
rotation, 14-8 
scaling, 14-3 
simple rotation, 14-8 
simple scaling, 14-3 
translation, 14-1 
uniform scaling, 14-6 
viewing, 2-1, 3-7 
world coordinate, 8-29 


U 


U1S$BEGIN-SEGMENT, 18-9 
U1S$C1RCLE, 18-11 
UIS$CLOSE-WINDOW, 18-14 
UlS$COPY-OBJECT, 18-15 
UlS$CREATE-COLOR-MAP, 18-20 
UlS$CREATE-COLOR-MAP-SEG, 18-23 
U1S$CREATE_D1SPLAY, 18-26 
U1S$CREATE-KB, 18-28 
U1S$CREATE-TB, 18-31 
U1S$CREATE-TERMINAL, 18-32 
U1S$CRE ATE-TRANSFORMATION, 18-34 
UlS$CREATE-WlNDOW, 18-37 
UlS$DELETE-COLOR-MAP, 18-46 
UlS$DELETE-COLOR_MAP-SEG, 18-47 
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UIS$DELETE_DISPLAY, 18-48 
UIS$DELETE_KB, 18-49 
UIS$DELETE_OBJECT, 18-50 
UIS$DELETE-PRIVATE, 18-51 
UIS$DELETE_TB, 18-52 
UIS$DELETE-TRANSFORMATION, 18-53 
UIS$DELETE-WINDOW, 18-54 
UIS$DIS ABLE-DISPLAY-LIST, 18-55 
UIS$DISABLE-KB, 18-58 
UIS$DISABLE-TB, 18-59 
UIS$DIS ABLE-VIE WPORT-KB, 18-60 
UIS$ELLIPSE, 18-61 
UIS$EN ABLE-DISPLAY-LIST, 18-65 
UIS$ENABLE-KB, 18-68 
UIS$ENABLE-TB, 18-70 
UIS$ENABLE-VIEWPORT-KB, 18-71 
UIS$END-SEGMENT, 18-72 
UIS$ERASE, 18-73 
UIS$EXECUTE, 18-75 
UIS$EXECUTE-DISPLAY, 18-77 
UIS$EXPAND-ICON, 18-78 
UIS$EXTRACT-HEADER, 18-81 
UIS$EXTRACT-OBJECT, 18-83 
UIS$EXTRACT-PRIVATE, 18-85 
UIS$EXTR ACT-REGION, 18-88 
UIS$EXTR ACT-TRAILER, 18-91 
UIS$FIND-PRIMITIVE, 18-93 
UIS$FIND-SEGMENT, 18-95 
UIS$GET-ABS-POINTER-POINTER- 
POS, 18-97 

UIS$GET-ALIGNED-POSITION, 18-98 
UIS$GET_ARC-TYPE, 18-100 
UIS$GET_BACKGROUND-INDEX, 18-102 
UIS$GET-BUTTONS, 18-103 
UIS$GET_CHAR-ROTATION, 18-105 
UIS$GET-CHAR-SIZE, 18-106 
UIS$GET-CHAR-SLANT, 18-108 
UIS$GET-CLIP, 18-112 
UIS$GET-COLOR, 18-115 
UIS$GET-COLORS, 18-118 
UIS$GET-CURRENT-OBJECT, 18-121 
UIS$GET_DISPLAY-SIZE, 18-123 
UIS$GET-FILL-PATTERN, 18-126 
UIS$GET_FONT, 18-129 
UIS$GET-FONT-ATTRIBUTES, 18-131 
UIS$GET-FONT-SIZE, 18-135 


UIS$GET-HW-COLOR-INFO, 18-137 
UIS$GET-INTENSITIES, 18-141 
UIS$GET-INTENSITY, 18-144 
UIS$GET-KB-ATTRIBUTES, 18-146 
UIS$GET-LINE-STYLE, 18-148 
UIS$GET-LINE-WIDTH, 18-150 
UIS$GET_NEXT-OBJECT, 18-153 
UIS$GET-OBJECT-ATTRIBUTES, 18-155 
UIS$GET-PARENT-SEGMENT, 18-158 
UIS$GET-POINTER-POSITION, 18-160 
UIS$GET-POSITION, 18-162 
UIS$GET-PREVIOUS_OBJECT, 18-164 
UIS$GET-ROOT-SEGMENT, 18-167 
UIS$GET_TB-INFO, 18-169 
UIS$GET-TB-POSITION, 18-172 
UIS$GET-TEXT-FORMATTING, 18-173 
UIS$GET-TEXT_MARGINS, 18-175 
UIS$GET_TEXT-PATH, 18-177 
UIS$GET-TEXT-SLOPE, 18-179 
UIS$GET-VCM-ID, 18-181 
UIS$GET-VIEWPORT-ICON, 18-182 
UIS$GET-VIEWPORT-POSITION, 18-184 
UIS$GET-VIEWPORT-SIZE, 18-186 
UIS$GET-VISIBILITY, 18-188 
UIS$GET-WINDOW-ATTRIBUTES, 18- 
190 

UIS$GET-WINDOW-SIZE, 18-191 
UIS$GET-WRITING-INDEX, 18-192 
UIS$GET-WRITING_MODE, 18-194 
UIS$GET-WS-COLOR, 18-195 
UIS$GET-WS-INTENSITY, 18-198 
UIS$HLS_TO-RGB, 18-200 
UIS$HSV-TO-RGB, 18-202 
UIS$IMAGE, 18-204 
UIS$INSERT-OBJECT, 18-209 
UIS$LINE, 18-210 
UIS$LINE-ARRAY, 18-213 
UIS$MEASURE-TEXT, 18-215 
UIS$MOVE-AREA, 18-221 
UIS$MOVE-VIEWPORT, 18-224 
UIS$MOVE-WINDOW, 18-226 
UIS$NEW-TEXT-LINE, 18-228 
UIS$PLOT, 18-229 
UIS$PLOT-ARRAY, 18-232 
UISSPOP-VIEWPORT, 18-234 
UIS$PRESENT, 18-236 
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UIS$PRIVATE, 18-237 
UIS$PUSH_VIEWPORT, 18-239 
UIS$READ_CHAR, 18-241 
UIS$RESIZE-WINDOW, 18-243 
UIS$RESTORE_CMS_COLORS, 18-246 
UIS$RGB_TO_HLS, 18-247 
UIS$RGB_TO_HSV, 18-249 
UIS$SET_ADDOPT_AST, 18-251 
UIS$SET_ALIGNED_POSITION, 18-253 
UIS$SET_ARC_TYPE, 18-255 
UIS$SET_BACKGROUND_INDEX, 18-258 
UIS$SET_BUTTON_AST, 18-260 
UIS$SET_CHAR_ROTATION, 18-264 
UIS$SET_CHAR_SIZE, 18-267 
UIS$SET_CHAR_SLANT, 18-271 
UIS$SET_CHAR_SPACING, 18-273 
UIS$SET_CLIP, 18-278 
UIS$SET_CLOSE_AST, 18-281 
UIS$SET_COLOR, 18-283 
UIS$SET_COLORS, 18-286 
UIS$SET_EXPAND_ICON_AST, 18-289 
UIS$SET_FILL-PATTERN, 18-291 
UIS$SET-FONT, 18-295 
UIS$SET-GAIN-KB-AST, 18-297 
UIS$SET-INSERTION-POSITION, 18-299 
UISSSET-INTENSITIES, 18-302 
UIS$SET-INTENSITY, 18-304 
UIS$SET-KB-AST, 18-306 
UIS$SET-KB-ATTRIBUTES, 18-308 
UIS$SET-KB-COMPOSE2, 18-311 
UIS$SET-KB-COMPOSE3, 18-313 
UIS$SET-KB-KEYTABLE, 18-315 
UIS$SET-LINE-STYLE, 18-317 
UIS$SET-LINE-WIDTH, 18-320 
UIS$SET-LOSE_KB-AST, 18-324 
UIS$SET-MOVE-INFO-AST, 18-326 
UIS$SET-POINTER_AST, 18-328 
UIS$SET_POINTER_PATTERN, 18-332 
UIS$SET-POINTER-POSITION, 18-335 
UIS$SET_POSITION, 18-337 
UIS$SET-RESIZE-AST, 18-339 
UIS$SET-SHRINK-TO-ICON-AST, 
18-344 

UIS$SET-TB-AST, 18-346 
UIS$SET-TEXT-FORMATTING, 18-349 
UIS$SET-TEXT-MARGINS, 18-353 


UIS$SET-TEXT-PATH, 18-355 
UIS$SET-TEXT-SLOPE, 18-358 
UIS$SET-WRITING-INDEX, 18-361 
UIS$SET-WRITING-MODE, 18-363 
UIS$SHRINK-TO_ICON, 18-365 
UIS$SOUND-BELL, 18-369 
UIS$SOUND_CLICK, 18-370 
UIS$TEST_KB, 18-371 
UIS$TEXT, 18-372 
UIS$TRANSFORM-OBJECT, 18-376 
UISDC$ ALLOC ATE-DOP, 19-3 
UISDCSCIRCLE, 19-5 
UISDC$ELLIPSE, 19-7 
UISDCSERASE, 19-10 
UISDC$EXECUTE_DOP-ASYNCH, 19-11 
UISDC$EXECUTE-DOP_SYNCH, 19-13 
UISDC$GET-ALIGNED-POSITION, 19-14 
UISDC$GET-CHAR_SIZE, 19-16 
UISDC$GET-CLIP, 19-18 
UISDC$GET-POINTER-POSITION, 19-20 
UISDC$GET-POSITION, 19-22 
UISDC$GET_TEXT-MARGINS, 19-23 
UISDC$GET-VISIBILITY, 19-25 
UISDC$IMAGE, 19-27 
UISDC$LINE, 19-31 
UISDC$LINE-ARRAY, 19-33 
UISDC$LO AD-BITMAP, 19-35 
UISDC$MEASURE-TEXT, 19-37 
UISDC$MOVE-AREA, 19-39 
UISDC$NEW-TEXT_LINE, 19-41 
UISDCSPLOT, 19-42 
UISDC$PLOT-ARRAY, 19-44 
UISDC$QUEUE-DOP, 19-46 
UISDC$READ-IMAGE, 19-47 
UISDC$SET-ALIGNED_POSITION, 19-50 
UISDC$SET-BUTTON-AST, 19-52 
UISDC$SET_CHAR_SIZE, 19-54 
UISDC$SET_CLIP, 19-56 
UISDC$SET-POINTER_AST, 19-58 
UISDC$SET-POINTER_PATTERN, 19-61 
UISDC$SET-POINTER-POSITION, 19-64 
UISDC$SET-POSITION, 19-65 
UISDC$SET-TEXT_MARGINS, 19-66 
UISDC$TEXT, 19-68 
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V 


VAX Procedure Calling Standard, 6-1 
Viewing object 

See Display window 
Viewport 

See Display viewport 
Virtual display, 2-8, 7-1 
aspect ratio, 2-8 
creating, 2-8, 7-3 
description of, 2-8 
panning, 8-12 
world coordinates, 2-8 
zooming, 8-12 
Virtual keyboard, 5-4 
assignment list, 17-3 
binding, 17-3 
creating, 17-3 
KB icon, 5-4 
VMS usage, 6-3 

W 


Window 

See Display window 
Windowing 

See Display window 
Windowing feature, 1-7 
Windowing routine, 8-1 
Workstation hardware, 1-1 
communications board, 1-4 
keyboard, 1-3 
monitor, 1-2 
mouse, 1-3 
printer, 1-4 
processor, 1-2 
tablet, 1-3 

Workstation standard color 
See Color system 

World coordinate transformation, 8-29 
scaling, 8-29 
two-dimensional, 8-29 
Writing color index 
See Attribute 
Writing mode 
See Attribute 
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